Mail Send

Send emails to one or more recipients. The API processes requests asynchronously and returns a 202 response that includes an operationId you can use to track send status.

Send to a single recipient

Send an email to a single recipient:

1curl -X POST 'https://comms.twilio.com/v1/Emails' \
2-H 'Content-Type: application/json' \
3-d '{
4    "from": {
5        "address": "support@example.com",
6        "name": "Support Team"
7    },
8    "to": [
9        {
10            "address": "john.doe@example.com",
11            "name": "John Doe"
12        }
13    ],
14    "content": {
15        "subject": "Your subject line",
16        "html": "<p>Your message content in HTML format.</p>",
17        "text": "Your message content in plain text."
18    }
19}' \
20-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response (202 Accepted):

1{
2    "operationId": "comms_operation_01h9krwprkeee8fzqspvwy6nq8",
3    "operationLocation": "https://comms.twilio.com/v1/Emails/Operations/comms_operation_01h9krwprkeee8fzqspvwy6nq8"
4}

Send to multiple recipients

Send the same email to multiple recipients:

1curl -X POST 'https://comms.twilio.com/v1/Emails' \
2-H 'Content-Type: application/json' \
3-d '{
4    "from": {
5        "address": "support@example.com",
6        "name": "Support Team"
7    },
8    "to": [
9        {
10            "address": "john.doe@example.com",
11            "name": "John Doe"
12        },
13        {
14            "address": "jane.smith@example.com",
15            "name": "Jane Smith"
16        }
17    ],
18    "content": {
19        "subject": "Your subject line",
20        "html": "<p>Your message content in HTML format.</p>",
21        "text": "Your message content in plain text."
22    }
23}' \
24-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Personalization with variables

Use Liquid templating to personalize emails for each recipient:

1curl -X POST 'https://comms.twilio.com/v1/Emails' \
2-H 'Content-Type: application/json' \
3-d '{
4    "from": {
5        "address": "support@example.com",
6        "name": "Support Team"
7    },
8    "to": [
9        {
10            "address": "jane.doe@example.com",
11            "variables": {
12                "firstName": "Jane",
13                "lastName": "Doe"
14            }
15        },
16        {
17            "address": "john.doe@example.com",
18            "variables": {
19                "firstName": "John",
20                "lastName": "Doe"
21            }
22        }
23    ],
24    "content": {
25        "subject": "Hello {{ firstName }}",
26        "html": "<html><body>Hey {{ firstName | default: '\''there'\'' }} {{ lastName }}, your order is ready.</body></html>",
27        "text": "Hey {{ firstName | default: '\''there'\'' }} {{ lastName }}, your order is ready."
28    }
29}' \
30-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Schedule an email

Schedule an email to be sent at a future time. Provide a sendAt value in RFC 3339 format. You can schedule emails up to 7 days in advance.

1curl -X POST 'https://comms.twilio.com/v1/Emails' \
2-H 'Content-Type: application/json' \
3-d '{
4    "from": {
5        "address": "support@example.com",
6        "name": "Support Team"
7    },
8    "to": [
9        {
10            "address": "john.doe@example.com",
11            "name": "John Doe"
12        }
13    ],
14    "content": {
15        "subject": "Scheduled Reminder",
16        "html": "<html><body>This is your scheduled reminder.</body></html>"
17    },
18    "schedule": {
19        "sendAt": ["2026-12-15T14:15:22Z"]
20    }
21}' \
22-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Custom headers

Add custom headers to your emails for tracking and categorization:

1curl -X POST 'https://comms.twilio.com/v1/Emails' \
2-H 'Content-Type: application/json' \
3-d '{
4    "from": {
5        "address": "marketing@example.com",
6        "name": "Marketing Team"
7    },
8    "to": [
9        {
10            "address": "customer@example.com",
11            "name": "Customer"
12        }
13    ],
14    "content": {
15        "subject": "Special Offer",
16        "html": "<html><body><h1>Exclusive Deal!</h1></body></html>",
17        "text": "Exclusive Deal!",
18        "headers": {
19            "X-Campaign-ID": "CAMPAIGN-2026-Q1",
20            "X-Customer-Segment": "premium",
21            "X-Priority": "high"
22        }
23    }
24}' \
25-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Note: You can't override these headers: x-sg-id, x-sg-eid, received, dkim-signature, Content-Type, Content-Transfer-Encoding, To, From, Subject, Reply-To, CC, BCC.

Tags for tracking

Add custom metadata tags to emails for filtering and tracking:

1curl -X POST 'https://comms.twilio.com/v1/Emails' \
2-H 'Content-Type: application/json' \
3-d '{
4    "from": {
5        "address": "newsletter@example.com",
6        "name": "Newsletter Team"
7    },
8    "to": [
9        {
10            "address": "john.doe@example.com",
11            "name": "John Doe"
12        }
13    ],
14    "content": {
15        "subject": "January Newsletter",
16        "html": "<html><body><h1>Newsletter</h1></body></html>"
17    },
18    "tags": {
19        "campaign": "monthlyNewsletter",
20        "edition": "january_2026"
21    }
22}' \
23-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

For more details on tag constraints, see Tags.