GuidesEmail

Email API

Overview

The Email API allows you to send emails through the Comms API. You can send emails to single or multiple recipients with personalization, scheduled delivery, custom headers and footers, and tracking tags.

Send an Email

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:

$curl -X POST 'https://comms.twilio.com/v1/Emails' \
>--header 'Content-Type: application/json' \
>--data '{
>    "from": {
>        "address": "support@example.com",
>        "name": "Support Team"
>    },
>    "to": [
>        {
>            "address": "john.doe@example.com",
>            "name": "John Doe"
>        }
>    ],
>    "content": {
>        "subject": "Your subject line",
>        "html": "<p>Your message content in HTML format.</p>",
>        "text": "Your message content in plain text."
>    }
>}' \
>-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:

$curl -X POST 'https://comms.twilio.com/v1/Emails' \
>--header 'Content-Type: application/json' \
>--data '{
>    "from": {
>        "address": "support@example.com",
>        "name": "Support Team"
>    },
>    "to": [
>        {
>            "address": "john.doe@example.com",
>            "name": "John Doe"
>        },
>        {
>            "address": "jane.smith@example.com",
>            "name": "Jane Smith"
>        }
>    ],
>    "content": {
>        "subject": "Your subject line",
>        "html": "<p>Your message content in HTML format.</p>",
>        "text": "Your message content in plain text."
>    }
>}' \
>-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Personalization with variables

Use Liquid templating to personalize emails for each recipient:

$curl -X POST 'https://comms.twilio.com/v1/Emails' \
>--header 'Content-Type: application/json' \
>--data '{
>    "from": {
>        "address": "support@example.com",
>        "name": "Support Team"
>    },
>    "to": [
>        {
>            "address": "jane.doe@example.com",
>            "variables": {
>                "firstName": "Jane",
>                "lastName": "Doe"
>            }
>        },
>        {
>            "address": "john.doe@example.com",
>            "variables": {
>                "firstName": "John",
>                "lastName": "Doe"
>            }
>        }
>    ],
>    "content": {
>        "subject": "Hello {{ firstName }}",
>        "html": "<html><body>Hey {{ firstName | default: '\''there'\'' }} {{ lastName }}, your order is ready.</body></html>",
>        "text": "Hey {{ firstName | default: '\''there'\'' }} {{ lastName }}, your order is ready."
>    }
>}' \
>-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Schedule an Email

Schedule an email to be sent at a future time:

$curl -X POST 'https://comms.twilio.com/v1/Emails' \
>--header 'Content-Type: application/json' \
>--data '{
>    "from": {
>        "address": "support@example.com",
>        "name": "Support Team"
>    },
>    "to": [
>        {
>            "address": "john.doe@example.com",
>            "name": "John Doe"
>        }
>    ],
>    "content": {
>        "subject": "Scheduled Reminder",
>        "html": "<html><body>This is your scheduled reminder.</body></html>"
>    },
>    "schedule": {
>        "sendAt": ["2026-12-15T14:15:22Z"]
>    }
>}' \
>-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Custom headers and footers

Add custom headers and footers to your emails:

$curl -X POST 'https://comms.twilio.com/v1/Emails' \
>--header 'Content-Type: application/json' \
>--data '{
>    "from": {
>        "address": "marketing@example.com",
>        "name": "Marketing Team"
>    },
>    "to": [
>        {
>            "address": "customer@example.com",
>            "name": "Customer"
>        }
>    ],
>    "content": {
>        "subject": "Special Offer",
>        "html": "<html><body><h1>Exclusive Deal!</h1></body></html>",
>        "text": "Exclusive Deal!",
>        "headers": {
>            "X-Campaign-ID": "CAMPAIGN-2026-Q1",
>            "X-Customer-Segment": "premium",
>            "X-Priority": "high"
>        },
>        "footer": {
>            "enabled": true,
>            "html": "<p style=\"font-size:11px;color:#666;\">Marketing Team | <a href=\"[unsubscribe]\">Unsubscribe</a></p>",
>            "text": "Marketing Team | Unsubscribe: [unsubscribe]"
>        }
>    }
>}' \
>-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

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:

$curl -X POST 'https://comms.twilio.com/v1/Emails' \
>--header 'Content-Type: application/json' \
>--data '{
>    "from": {
>        "address": "newsletter@example.com",
>        "name": "Newsletter Team"
>    },
>    "to": [
>        {
>            "address": "john.doe@example.com",
>            "name": "John Doe"
>        }
>    ],
>    "content": {
>        "subject": "January Newsletter",
>        "html": "<html><body><h1>Newsletter</h1></body></html>"
>    },
>    "tags": {
>        "campaign": "monthlyNewsletter",
>        "edition": "january_2026"
>    }
>}' \
>-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Tags can have up to 10 key-value pairs for organizing and filtering emails.