How emails are structured

The structure of the request JSON payload represents the email you want to send. Among other things, it defines the sender, recipients, subject, and body of an email. The personalizations field allows you to specify unique content for each recipient of an email. You can create highly targeted and individualized email campaigns within a single API call.

Basic structure

The personalizations array applies per-recipient overrides on top of the root-level fields. This structure allows for sending to multiple recipients, customizing subject lines per recipient, and applying different headers or DKIM settings per email. The example below sends a fruit sale to three recipients. The first two entries override the sender, subject, and cc/bcc recipients; the third entry only overrides the subject and falls back to the root-level sender:

{
  "personalizations": [
    {
      "to": [
        { "name": "Banana Lover", "email": "banana-lover123@example.com" }
      ],
      "cc": [
        { "email": "banana-fans@example.com" }
      ],
      "from": {
        "name": "Banana Department",
        "email": "bananas@fruitstand.example.com"
      },
      "subject": "🍌 BANANAS ARE ON SALE 🍌"
    },
    {
      "to": [
        { "name": "Apple Lover", "email": "apple-lover123@example.com" }
      ],
      "cc": [
        { "email": "apple-fans@example.com" }
      ],
      "bcc": [
        { "email": "archive@fruitstand.example.com" }
      ],
      "from": {
        "name": "Apple Department",
        "email": "apples@fruitstand.example.com"
      },
      "subject": "🍎 APPLES ARE ON SALE 🍎"
    },
    {
      "to": [
        { "name": "苹果爱好者", "email": "pingguo-fan@example.com" }
      ]
    }
  ],
  "from": {
    "name": "Fruit Stand",
    "email": "sales@fruitstand.example.com"
  },
  "subject": "Big sale this week",
  "content": [
    {
      "type": "text/plain",
      "value": "Don't miss our fruit sale this week!"
    },
    {
      "type": "text/html",
      "value": "<p>Don't miss our fruit sale this week!</p>"
    }
  ]
}

When a property is defined both globally and in a personalization object, the value in the personalization object is used.

Field types

Detailed definitions of each field can be found in the API reference.

The to field is the only required property within each personalization object.

personalizations: Array of objects (recipient-specific data)
from: Object (sender information)
subject: String
content: Array of objects (email body parts)

Each content object contains:

type: String (e.g., “text/plain”, “text/html”)
value: String (actual content)

Each EmailAddress object (sender or recipient information) contains:

name: String, optional. Display name as raw, unencoded text (e.g., John Doe, 张三).
email: String (e.g., foo@example.com).

Always provide the name field as raw, unencoded text to prevent double-encoding issues. Special characters and non-ASCII text will be automatically handled for email compatibility.