Migrating from SendGrid

The request shape is the same

SendGrid's mail send takes a from object whose email is required, a subject, and personalizations. Ours is POST /emails with from, to, subject, html and text. The full shape is on the POST /emails page.

Headers

headers takes a map of name to value. From, To, Subject, Message-ID and Date are refused in headers.

Error names resolve

SendGrid error names are not aliases here. Branch on our code. Every refusal carries message, fix and docs_url. The catalogue is at /docs/errors.

Payload map

Fetched from the mail-send reference on 2026-09-28 (https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send). That page does not document an idempotency key.

Webhook events

The pages fetched on 2026-09-28 (pricing, the free-plan changelog, the docs MCP server, and mail send) do not name webhook event types. Each of our types is listed so the gap is visible. Do not invent a SendGrid name for a row that says so.

What will refuse on day one

• Inbound mail is not offered. A migration that depends on receiving mail at your domain does not have that path here.
• Keeping customer data in the EU is not offered. Data is processed in the United States.
• There is no business associate agreement for health data.
• A key is created with a send budget. A key that sends past the budget is refused with agent_budget_exceeded rather than invoiced.

The compatibility client, when the import line is all you want to change

That client mirrors one provider's SDK (agentisend/compat-resend). It does not mirror this provider. Call POST /emails with from, to, subject, html and text.

Contacts

POST /contacts accepts first_name, last_name, unsubscribed and properties. unsubscribed: true records that the person asked not to receive marketing mail. GET, PATCH and DELETE /contacts/{id} take the contact id or the email address. The SendGrid pages fetched on 2026-09-28 cover pricing, the mail-send reference and the docs MCP server. They do not document a contact-import field map, so this guide does not invent one. Add each person with POST /contacts. An API key cannot lift an unsubscribe.

The bounce return path

A domain that already sends from somewhere else often has an MX record on send. Creating it here without a return-path label then uses bounce instead of refusing the domain. To choose the label, pass custom_return_path on POST /domains.

Two differences, both deliberate

Keys have budgets, and the budget is enforced. Set the budget to your real volume before you cut over.

Inbound mail and an EU data region are not part of the move. If the old account uses either, that part stays on the old provider.

What you gain in the move

• Per-key budgets and one kill switch for the account, on Budgets and the kill switch.
• An approval queue for a send the loop guard flags, or one an agent asks about with request_approval, on Approvals.
• Signed webhooks, a replay call, and a dead-letter list, on Webhooks.

Order of operations

1. Add and verify your domains here while the old provider still sends.
2. Create keys with budgets, one per sender, and point webhooks at the new signing scheme.
3. Move a low-volume stream first.
4. Move the rest, and keep the old keys alive until you have a week of clean data.