Expand
Rate this page:

Personalizations

When sending an email with the v3 Mail Send endpoint, you define the various metadata about your message, such as the recipients, sender, subject, and send time, at the root level of a JSON request body. Personalizations allow you to override these various metadata for each email in an API request.

Personalizations is an array of objects. Think of the personalizations array like the envelope of a letter: the fields defined within personalizations apply to each email, not the recipient. Like an envelope, personalizations are used to identify who should receive the email as well as details 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.
  • "from" - The sender or return path address 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 property 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 jane@example.com but set each email to be delivered at different times.

{
  "from": "sender@yourdomain.com",
  "template_id": "YOUR TEMPLATE ID",
  "personalizations": [
    {
      "to": [
        {
          "email": "john@example.com"
        }
      ],
      "send_at": 1600188812
    },
    {
      "to": [
        {
          "email": "jane@example.com"
        }
      ],
      "send_at": 1600275471
    }
  ]
}

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.

Some properties can be defined both at the root level of the request body (message level) and at the personalizations level.

For example, the from, subject, headers, custom_arg, and send_at properties can all be defined at the message level or at the personalizations level. Individual fields within the personalizations array will override any message level properties 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 such as 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 (specified in the to, cc, or bcc fields) will see the same email, as defined by the data in that personalization. Because of this, SendGrid does not allow duplicate email addresses among these three recipient arrays in a single personalization.

{
  "personalizations": [
    {
      "to": [
        {
          "email": "recipient1@example.com"
        }
      ],
      "cc": [
        {
          "email": "recipient2@example.com"
        }
      ],
      "subject": "YOUR SUBJECT LINE GOES HERE"
    }
  ]
}
using SendGrid;
using SendGrid.Helpers.Mail;
using System;
using System.Threading.Tasks;

namespace Example
{
    internal class Example
    {
        private static void Main()
        {
            Execute().Wait();
        }

        static async Task Execute()
        {
            var apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY");
            var client = new SendGridClient(apiKey);
            var from = new EmailAddress("test@example.com", "Example User");
            var subject = "Sending with Twilio SendGrid is Fun";
            var to = new EmailAddress("test@example.com", "Example User");
            var plainTextContent = "and easy to do anywhere, even with C#";
            var htmlContent = "<strong>and easy to do anywhere, even with C#</strong>";
            var msg = MailHelper.CreateSingleEmail(from, to, subject, plainTextContent, htmlContent);
            var response = await client.SendEmailAsync(msg);
        }
    }
}

Sending a single email to a single recipient with substitutions

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

{
  "personalizations": [
    {
      "to": [
        {
          "email": "recipient@example.com"
        }
      ],
      "substitutions": {
        "%fname%": "recipient",
        "%CustomerID%": "CUSTOMER ID GOES HERE"
      },
      "subject": "YOUR SUBJECT LINE GOES HERE"
    }
  ]
}
using SendGrid;
using SendGrid.Helpers.Mail;
using System.Threading.Tasks;
using System;

namespace Example
{
    internal class Example
    {
        private static void Main()
        {
            Execute().Wait();
        }

        static async Task Execute()
        {
            var apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY");
            var client = new SendGridClient(apiKey);
            var msg = new SendGridMessage();
            msg.SetFrom(new EmailAddress("test@example.com", "Example User"));
            msg.SetSubject("I'm replacing the subject tag");
            msg.AddTo(new EmailAddress("test@example.com", "Example User"));
            msg.AddContent(MimeType.Text, "I'm replacing the <strong>body tag</strong>");
            msg.SetTemplateId("13b8f94f-bcae-4ec6-b752-70d6cb59f932");
            msg.AddSubstitution("-name-", "Example User");
            msg.AddSubstitution("-city-", "Denver");
            var response = await client.SendEmailAsync(msg);
            Console.WriteLine(response.StatusCode);
            Console.WriteLine(response.Headers.ToString());
            Console.WriteLine("\n\nPress any key to exit.");
            Console.ReadLine();
        }
    }
}

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.

{
  "personalizations": [
    {
      "to": [
        {
          "email": "recipient1@example.com"
        }
      ],
      "cc": [
        {
          "email": "recipient2@example.com"
        }
      ],
      "subject": "YOUR SUBJECT LINE GOES HERE"
    }
  ]
}

word word

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.

{
  "personalizations": [
    {
      "to": [
        {
          "email": "recipient1@example.com"
        }
      ],
      "cc": [
        {
          "email": "recipient2@example.com"
        }
      ],
      "bcc": [
        {
          "email": "recipient3@example.com"
        }
      ]
    }
  ]
}

word word word word word

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.

{
  "personalizations": [
    {
      "to": [
        {
          "email": "recipient1@example.com"
        },
        {
          "email": "recipient2@example.com"
        },
        {
          "email": "recipient3@example.com"
        }
      ],
      "subject": "YOUR SUBJECT LINE GOES HERE"
    }
  ]
}
using SendGrid;
using SendGrid.Helpers.Mail;
using System;
using System.Threading.Tasks;
using System.Collections.Generic;

namespace Example
{
    internal class Example
    {
        private static void Main()
        {
            Execute().Wait();
        }

        static async Task Execute()
        {
            var apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY");
            var client = new SendGridClient(apiKey);

            var from = new EmailAddress("test@example.com", "Example User");
            var tos = new List<EmailAddress>
            {
                new EmailAddress("test1@example.com", "Example User1"),
                new EmailAddress("test2@example.com", "Example User2"),
                new EmailAddress("test3@example.com", "Example User3")
            };
            var subject = "Sending with Twilio SendGrid is Fun";
            var plainTextContent = "and easy to do anywhere, even with C#";
            var htmlContent = "<strong>and easy to do anywhere, even with C#</strong>";
            var showAllRecipients = false; // Set to true if you want the recipients to see each others email addresses

            var msg = MailHelper.CreateSingleEmailToMultipleRecipients(from,
                                                                       tos,
                                                                       subject,
                                                                       plainTextContent,
                                                                       htmlContent,
                                                                       showAllRecipients
                                                                       );
            var response = await client.SendEmailAsync(msg);
        }
    }
}

Sending a single email to a single recipient with multiple CCs and BCCs

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

{
  "personalizations": [
    {
      "to": [
        {
          "email": "recipient1@example.com"
        }
      ],
      "cc": [
        {
          "email": "recipient2@example.com"
        },
        {
          "email": "recipient3@example.com"
        },
        {
          "email": "recipient4@example.com"
        }
      ],
      "subject": "YOUR SUBJECT LINE GOES HERE"
    }
  ]
}

word word word word word

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.

{
  "personalizations": [
    {
      "to": [
        {
          "email": "recipient1@example.com"
        }
      ],
      "cc": [
        {
          "email": "recipient2@example.com"
        },
        {
          "email": "recipient3@example.com"
        },
        {
          "email": "recipient4@example.com"
        }
      ],
      "subject": "YOUR SUBJECT LINE GOES HERE"
    },
    {
      "to": [
        {
          "email": "recipient5@example.com"
        }
      ],
      "cc": [
        {
          "email": "recipient6@example.com"
        },
        {
          "email": "recipient7@example.com"
        },
        {
          "email": "recipient8@example.com"
        }
      ],
      "subject": "YOUR SUBJECT LINE GOES HERE"
    }
  ]
}

word word word word word

Sending multiple emails from multiple senders to multiple recipients

It is possible to specify multiple From addresses using personalizations. If a personalization object does not contain a from object, SendGrid will use the email address in the from object defined at the root level of the request body.

To successfully deliver email using multiple From addresses, the following conditions must be met.

  • A from object with an email property must be specified at the root level of the request body.
  • The domain of the from email property specified in any personalization must match the domain of the from email property specified at root level of the request body—SendGrid will reject requests if these domains do not match.
// This is valid
{
  "from": {
    "email": "support@example.com"
  },
  "personalizations": [
    {
      "from": {
        "email": "noreply@example.com"
      }
    }
  ]
}

// This is invalid
{
  "from": {
    "email": "support@example.com"
  },
  "personalizations": [
    {
      "from": {
        "email": "noreply@differentexample.com"
      }
    }
  ]
}

word word word

The following shows how to send multiple emails using three different from addresses on the same domain.

You must complete domain authentication to send email from multiple addresses. SendGrid will reject requests from a sending domain that has not been authenticated.

{
  "from": {
    "email": "default@samedomain.com"
  },
  "personalizations": [
    {
      "subject": "YOUR SUBJECT LINE GOES HERE",
      "to": [
        {
          "email": "recipient1@example1.com"
        }
      ],
      "from": {
        "email": "sender1@samedomain.com"
      }
    },
    {
      "subject": "YOUR SUBJECT LINE GOES HERE",
      "to": [
        {
          "email": "recipient2@example2.com"
        }
      ],
      "from": {
        "email": "sender2@samedomain.com"
      }
    },
    {
      "subject": "YOUR SUBJECT LINE GOES HERE",
      "to": [
        {
          "email": "recipient3@example3.com"
        }
      ],
      "from": {
        "email": "sender3@samedomain.com"
      }
    }
  ]
}
using SendGrid;
using SendGrid.Helpers.Mail;
using System;
using System.Threading.Tasks;
using System.Collections.Generic;

namespace Example
{
    internal class Example
    {
        private static void Main()
        {
            Execute().Wait();
        }

        static async Task Execute()
        {
            var apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY");
            var client = new SendGridClient(apiKey);

            var from = new EmailAddress("test@example.com", "Example User");
            var tos = new List<EmailAddress>
            {
                new EmailAddress("test1@example.com", "Example User1"),
                new EmailAddress("test2@example.com", "Example User2"),
                new EmailAddress("test3@example.com", "Example User3")
            };
            var subjects = new List<string> { "Test Subject1", "Test Subject2", "Test Subject3" };
            var plainTextContent = "Hello -name-";
            var htmlContent = "Goodbye -name-";
            var substitutions = new List<Dictionary<string, string>>
            {
                new Dictionary<string, string>() {{"-name-", "Name1"}},
                new Dictionary<string, string>() {{"-name-", "Name2"}},
                new Dictionary<string, string>() {{"-name-", "Name3"}}
            };

            var msg = MailHelper.CreateMultipleEmailsToMultipleRecipients(from,
                                                                          tos,
                                                                          subjects,
                                                                          plainTextContent,
                                                                          htmlContent,
                                                                          substitutions
                                                                          );
            var response = await client.SendEmailAsync(msg);
        }
    }
}
Rate this page:

Need some help?

We all do sometimes. Get help now from the Twilio SendGrid Support Team.

Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.

Loading Code Sample...
        
        
        

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        thanks-feedback-gif