Personalizing your emails

What is email personalization?

Email personalization is one of the most important point under the best practices of the email. Personalization shows that you care about making a connection with your recipients and helps mail seem less like a bulk message and more like a one to one personal or a notification email.

Examples of personalization include addressing the recipient of your email by their name, drafting content based on their personal interests, and so on.

In the SendEmail API, the various metadata about the message such as the recipients, x-apiheader, attributes and CC are contained within an array called personalizations.

Personalization section is like the envelope of a letter: the fields defined within the personalizations apply to each individual emails. You can define stuff like who should receive your email, who should be kept in cc, custom arguments you would like to be included with the email or any type of substitutions which need to be done inside the email content.

Personalizations allow you to define:

  • recipient, recipient_cc - The recipients of your email.

  • attributes - Any substitutions you would like to be made for your email. Example; you would like to replace Dear [%NAME%] with the actual NAME of the recipient. Here, NAME is referred to be as an attribute of the recipient. Syntax to mention attribute within your HTML content, subject line is [%ATTRIBUTE_NAME%]

  • x-apiheader, X-TAGS, x-apiheader_cc - Any custom arguments you would like to include in your email like Invoice ID, Your internal transactionID etc. This is primarily to track each email messages uniquely in your application.

You must include at least one recipient object within the personalizations array.

Since the personalizations parameter is an array, you may include multiple objects allowing you to specify different handling instructions for different copies of your email. For example, you could send the same email to both steve@example.com and jenny@example.com, but set each email with a different set of recipients in their CC.

While there is no limit on the number of personalization objects which you can add in a single API call, but still it is recommended to not include more than 5000 personalizations per API request. If you need to include more than 5000 personalizations, please divide these across multiple API requests.

Keys within object “attributes” will be merged with its respective value in the emails. Example:

"attributes": {
    "NAME": "Mike",
    "ACCOUNT_BAL": "100"
}

This means, anywhere inside the email content, if the system founds [NAME] or [ACCOUNT_BAL], then it will be replaced with its respective values Mike and 100.

If you have passed the content of email as:

Dear [%NAME%],
Your account balance for this month is $[%ACCOUNT_BAL%].
Thanks,
ABC Bank Ltd

then it will get replaced with below final content:

Dear Mike,
Your account balance for this month is $100.
Thanks,
ABC Bank Ltd

Below are some examples of how you can use personalizations for various use cases.

Warning: Some samples are using curl utility for API examples. UNIX shells require that some characters must be escaped, for example $ becomes $. If your API key contains unescaped characters you may receive HTTP error 401 (Unauthorized).

Sending a Single Email to a Single Recipient with a CC

The following example shows how to send one email to user1@example.com with a carbon copy sent to user2@example.com. Both emails will have the same content and other parameters.

{
  "personalizations": [
    {
      "recipient": "user1@example.com",
      "attributes": {
        "NAME": 
          "Mike",
        "ACCOUNT_BAL": 
          "100"
      },
       "recipient_cc":"user2@example.com"
    }
  ],
  "from": {
    "fromEmail": "sales@mydomain.com",
    "fromName": "ABC Sales"
  },
  "subject": "Welcome to ABC Ltd",
  "content": "Hi [%NAME%], This is my first test email",
  "replyToId": "support@mydomain.com"
}

Sending a Single Email to a Single Recipient with a CC and a BCC

The following example shows how to send one email to user1@example.com with a CC sent to user2@example.com and a BCC sent to user3@example.com.

{
  "personalizations": [
    {
      "recipient": "user1@example.com",
      "attributes": {
        "NAME": 
          "Mike",
        "ACCOUNT_BAL":
          "100"
      },
       "recipient_cc":"user2@example.com"
    }
  ],
  "from": {
    "fromEmail": "sales@mydomain.com",
    "fromName": "ABC Sales"
  },
  "subject": "Welcome to ABC Ltd",
  "content": "Hi [%NAME%], This is my first test email",
  "settings": {
    "bcc": "user3@example.com"
  },
  "replyToId": "support@mydomain.com"
}

Sending a Single Email to Multiple Recipients

The following shows how to send one email to three different recipients: user1@example.com, user2@example.com, and user3@example.com. These recipients will all be able to see each other on the email.

{
  "personalizations": [
    {
     "recipient": "user1@example.com",
     "x-apiheader": "TRANSID1",
     "recipient_cc":["usercc1@example.com","usercc2@example.com"],
     "x-apiheader_cc":["TRANSID_CC1","TRANSID_CC2"]
    },
    {
     "recipient": "user2@example.com",
     "x-apiheader": "TRANSID2",
     "recipient_cc":["usercc3@example.com","usercc4@example.com"],
     "x-apiheader_cc":["TRANSID_CC3","TRANSID_CC4"]
    },
    {
     "recipient": "user3@example.com",
     "x-apiheader": "TRANSID3",
     "recipient_cc":["usercc5@example.com","usercc6@example.com"],
     "x-apiheader_cc":["TRANSID_CC5","TRANSID_CC6"]
    }
  
 ],
       
  "from": {
    "fromEmail": "sales@mydomain.com",
    "fromName": "ABC Sales"
  },
  "subject": "Welcome to ABC Ltd",
  "content": "Hi [%NAME%], This is my first test email",
  "settings": {
    "bcc": "mybcc@example.com"
  },
  "replyToId": "support@mydomain.com"
}

Sending a Single Email to a Single Recipient with Multiple CCs

The following shows what personalizations are required to send the same email to one recipient, with multiple CCs.

{
  "personalizations": [
    {
      "recipient": "user1@example.com",
       "attributes": {
        "NAME": 
          "Mike",
        "ACCOUNT_BAL":
          "100"
      },
      
      "recipient_cc": [
        "usercc1@example.com",
        "usercc2@example.com"
      ]
    }
  ],
  "from": {
    "fromEmail": "sales@mydomain.com",
    "fromName": "ABC Sales"
  },
  "subject": "Welcome to ABC Ltd",
  "content": "Hi [%NAME%], This is my first test email",
  "settings": {
    "bcc": "mybcc@example.com"
  },
  "replyToId": "support@mydomain.com"
}