When sending email via the v3 Mail Send endpoint, the various metadata about the message (such as the recipients, subject line, headers, substitutions, and custom arguments) are contained within an array called personalizations.

Think of the personalizations section of the request body like the envelope of a letter: the fields defined within personalizations apply to each individual email, not the recipient. Like an envelope, personalizations are used to identify who should receive the email as well as specifics about how you would like the email to be handled. For example, you can define when you would like it to be sent, what headers you would like to include, and any substitutions or custom arguments you would like to be included with the email.

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.

You must include at least one “to” 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 <john@example.com> and <janeexampexample@example.com>, but set each email to be delivered at different times.

You may not include more than 1000 personalizations per API request. If you need to include more than 1000 personalizations, please divide these across multiple API requests.

There are certain parameters that can be defined both at the “message level” and at the “personalizations” level.

For example, the subject, headers, custom arguments, and send_at parameters can all be defined globally or at the personalizations level. When SendGrid processes and validates your request, it first looks at the globally defined parameters. Then the personalizations you have specified are applied, overriding any duplicates already specified globally.

Individual fields within the personalization array will override any other global, or “message level”, parameters that are defined outside of personalizations. For example, the email subject defined within personalizations will override the subject defined at the message level in the JSON payload.

Keys within objects like custom_args will be merged. If any of the keys conflict, the keys in the personalizations object will replace the message level object’s keys.

All of the recipients in a single personalization object (either in the to, cc, or bcc fields), will see exactly the same email, as defined by the data in that personalization, as such we do not allow duplicate emails between these three arrays in a single personalization.

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

Personalization Examples Index

Sending a Single Email to a Single Recipient

The following example shows you what the personalization parameter would look like if you wanted to send a single email to a single recipient.

1
2
3
4
5
6
7
8
9
10
11
12
{
  "personalizations": [{
      "to": [{
          "email": "recipient@example.com"
      }],
      "substitutions": {
          "%fname%": "recipient",
          "%CustomerID%": "CUSTOMER ID GOES HERE"
      },
      "subject": "YOUR SUBJECT LINE GOES HERE"
  }]
}

Sending a Single Email to a Single Recipient With a CC

The following example shows how to send one email to recipient1@example.com with a carbon copy sent to recipient2@example.com. Both emails will have the same headers.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "personalizations": [{
      "to": [{
          "email": "recipient1@example.com"
      }],
      "cc": [{
          "email": "recipient2@example.com"
      }],
      "substitutions": {
          "%fname%": "recipient",
          "%CustomerID%": "CUSTOMER ID GOES HERE"
      },
      "subject": "YOUR SUBJECT LINE GOES HERE"
  }]
}

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

The following example shows how to send one email to recipient1@example.com with a CC sent to recipient2@example.com and a BCC sent to recipient3@example.com.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "personalizations": [{
      "to": [{
          "email": "recipient1@example.com"
      }],
      "cc": [{
          "email": "recipient2@example.com"
      }],
      "bcc": [{
          "email": "recipient3@example.com"
      }],
      "substitutions": {
          "%fname%": "recipient",
          "%CustomerID%": "CUSTOMER ID GOES HERE"
      }
  }]
}

Sending the same Email to Multiple Recipients

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "personalizations": [{
      "to": [{
          "email": "recipient1@example.com"
      }, {
          "email": "recipient2@example.com"
      }, {
          "email": "recipient3@example.com"
      }],
      "substitutions": {
          "%fname%": "recipient",
          "%CustomerID%": "CUSTOMER ID GOES HERE"
      },
      "subject": "YOUR SUBJECT LINE GOES HERE"
  }]
}

Sending a Single Email to a Single Recipient With Multiple CCs/BCCs

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "personalizations": [{
      "to": [{
          "email": "recipient1@example.com"
      }],
      "cc": [{
          "email": "recipient2@example.com"
      }, {
          "email": "recipient3@example.com"
      }, {
          "email": "recipient4@example.com"
      }],
      "substitutions": {
          "%fname%": "recipient",
          "%CustomerID%": "CUSTOMER ID GOES HERE"
      },
      "subject": "YOUR SUBJECT LINE GOES HERE"
  }]
}

Sending Two Different Emails to Two Different Groups of Recipients

The following shows how to send two different emails to two different groups of recipients.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
  "personalizations": [{
      "to": [{
          "email": "recipient1@example.com"
      }],
      "cc": [{
          "email": "recipient2@example.com"
      }, {
          "email": "recipient3@example.com"
      }, {
          "email": "recipient4@example.com"
      }],
      "substitutions": {
          "%fname%": "recipient",
          "%CustomerID%": "CUSTOMER ID GOES HERE"
      },
      "subject": "YOUR SUBJECT LINE GOES HERE"
  }, {
      "to": [{
          "email": "recipient5@example.com"
      }],
      "cc": [{
          "email": "recipient6@example.com"
      }, {
          "email": "recipient7@example.com"
      }, {
          "email": "recipient8@example.com"
      }],
      "substitutions": {
          "%fname%": "recipient2",
          "%CustomerID%": 55
      },
      "subject": "YOUR SUBJECT LINE GOES HERE"
  }]
}