Add personalizations to an email

[slashdotdash]

SendGrid personalizations are used to identify who should receive the email as well as specifics about how you would like the email to be handled.

Personalizations allow you to define:

• to, cc, bcc - The recipients of your email.
• subject - The subject of your email.
• headers - Any headers you would like to include in your email.
• substitutions - Any substitutions you would like to be made for your email.
• custom_args - Any custom arguments you would like to include in your email.
• send_at - A specific time that you would like your email to be sent.

Multiple personalizations may be added to an email allowing you to specify different handling instructions for different copies of your email. For example, you could send the same email to both john@example.com and janeexampexample@example.com, but set each email to be delivered at different times.

Example

alias SendGrid.{Email, Personalization}

personalization =
  Personalization.build()
  |> Personalization.add_to("recipient1@example.com")
  |> Personalization.add_cc("recipient2@example.com")

Email.build()
|> Email.add_from("sender@example.com")
|> Email.add_personalization(personalization)
|> SendGrid.Mailer.send()

[alexgaribay]

Thanks for the PR.

I see the need for multiple personalizations per request but I feel that it complicates the API and flow. One of my goals with the Email portion was simplicity with the email. Personalizations seem to duplicate some of the API from API.

I have a v2 branch that changes some of the serialization behavior but also adopts protocols. I think that Personalizations can just act as a struct with a customized Jason.Encoder implementation. Email can still have a the added personalizations key with a new function like to_personalization (or that can be Personalizations.from_email.

[slashdotdash]

Do you plan to support email personalizations in v2?

The API for building personlizations duplicates building emails because many fields can be overridden in each personalisation. I’m currently using this feature in production to batch send thousands of emails which is only possible by batching the requests via personalizations.

[alexgaribay]

Yes. We can work this feature into v2 before I push it to Hex.

[alexgaribay]

I added in some of your changes in to another branch but I didn't take all of them. It's close to what you had functionally. The main difference is that I changed it to where Personalizations are created out of Emails. Here's what I have in the readme as an example:

alias SendGrid.{Mail, Email}

personalization_1 =
  Email.build()
  |> Email.add_to("john@example.com")
  |> Email.put_subject("Exciting news!")
  |> Email.to_personalization()

personalization_2 =
  Email.build()
  |> Email.add_to("jane@example.com")
  |> Email.put_subject("We've some exciting news!")
  |> Email.to_personalization()

Email.build()
|> Email.put_from("news@mydomain.com")
|> Email.put_text("...")
|> Email.put_html("...")
|> Email.add_personalization(personalization_1)
|> Email.add_personalization(personalization_2)
|> Mail.send()

You can take a look at the added code in 40bb0c7ec0aca34a91a469fc3058115d26052465. Try it out on the v2.0.0 branch and let me know if this works for you. Keep in mind that there's some other changes in that branch. 👍

[slashdotdash]

@alexgaribay Thanks for merging in the changes for v2.