Personalization data
This is the limit to understand before you design anything around templates.
variables applies to the whole request, not to each recipient. A send to
ten addresses renders the template once and delivers the identical body to all
ten.
{
"to": ["alice@example.com", "bob@example.com"],
"template_id": "8c1d4f2a-6b3e-4d19-9a27-5e0f1c8b7a44",
"variables": { "first_name": "Alice" }
}
Bob receives a message addressed to Alice. There is no per-recipient variable map, and no mail-merge over a recipient list.
One message per recipient
Real personalization means one message each, which is what
batch sending is for. A batch takes up to 500 independent
messages in one call, and each carries its own recipient, its own
template_id and its own variables.
{
"messages": [
{
"from": "receipts@yourcompany.com",
"to": ["alice@example.com"],
"template_id": "8c1d4f2a-6b3e-4d19-9a27-5e0f1c8b7a44",
"variables": { "first_name": "Alice", "order_id": "12345" }
},
{
"from": "receipts@yourcompany.com",
"to": ["bob@example.com"],
"template_id": "8c1d4f2a-6b3e-4d19-9a27-5e0f1c8b7a44",
"variables": { "first_name": "Bob", "order_id": "12346" }
}
]
}
Each entry is a complete send, so each is rendered separately against its own variables.
Entries in a batch succeed and fail independently. The response carries one
result per message, keyed by index, so a template error in message 7 does
not stop messages 1 to 6 going out.
Mixing templates in one batch
Nothing requires the entries to share a template. A batch can send three
different templates to three people, because each entry resolves its own
template_id. Equally, an entry can omit template_id and supply inline
subject, html and text. What it cannot do is both, which is the same
mutual exclusion as a single send.
Where personalization data should live
The platform stores no recipient attributes. There is no contact list, no audience, no merge-field store that a template draws from. Every value a template renders arrives in the request that sends it.
That is a deliberate boundary rather than a missing feature: your database
already knows your users, and a copy of it here would be a second thing to keep
correct and a second place to honour a deletion request. It does mean the
assembly, the loop over your recipients and the building of each variables
map, is work your application does.
Sizing a batch
500 messages is the per-call ceiling. For a larger run, send several batches. Each message in a batch is still a message for rate, allowance and reputation purposes, so a batch is a convenience, not a discount.