JSON, or multipart with each nested field (to, cc, bcc, from, custom_headers, tracking_options) as a JSON string and each attachment a file part. custom_headers may hold X-*, List-Unsubscribe, List-Unsubscribe-Post, Reply-To, Content-Type (text/plain makes a text-only mail) and, ours, In-Reply-To and References; anything else, or a line break, is 400 errors/invalid_headers. At most 500 recipients and 25 MB of attachments. Idempotency-Key makes a retry answer the first send (keys are per mailbox: the same key on two mailboxes is two sends). A mailbox that is not OK is still queued (gateway.account_status says its status). 404 means the mailbox is gone; a reply_to that names no mail is 422 errors/parent_mail_not_found.
Your API key from the console (gw_live_…).
In: header
Header Parameters
1 to 255 characters: a retry with the same key answers the first send instead of sending again.
length <= 255TypeScript Definitions
Use the request body type in TypeScript.
The send body, plus Swarmhit's body_plain, message_id and JSON attachments. In multipart, nested fields are JSON strings and attachments are file parts.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/email/api/v1/emails" \ -H "Content-Type: application/json" \ -d '{ "account_id": "em_gX2kP9qL4mT7vB1nR8sW3yZ", "to": [ { "display_name": "Lead", "identifier": "lead@example.com" } ], "subject": "Quick question", "body": "<p>Hi there</p>", "message_id": "7f3a9c@acme.com", "tracking_options": { "opens": true, "links": true, "label": "step-1" } }'{ "object": "EmailSent", "tracking_id": "7f3a9c@acme.com", "provider_id": null, "provider_immutable_id": null, "gateway": { "message_id": "<7f3a9c@acme.com>", "queue_id": "18c1f0e2a3b4c5d6", "send_at": null, "account_status": "OK" }}List emails GET
Live from the mailbox, newest first. One folder at a time: `folder` (its `provider_id` or `emf_` id), else `role`'s folder, else All Mail where the mailbox has it (Gmail), else INBOX. Items are `1_meta` (no body); `include_body=true` (ours) fetches the bodies when `limit` is 25 or less. The filters other than the folder search the folder.
Mark read or unread, or move an email PUT
`unread` wins over everything else. `folders`: one folder name for IMAP and Outlook (a move; the email's id changes with its folder, the new one is `gateway.email_id`). On Gmail, the folder names (as `folders` lists them; a system label such as `\Starred` as it is) become the mail's labels: the ones named are added; of the others, only user labels and INBOX, Trash and Spam are removed. Important, Starred, Draft and Sent stay unless named; All Mail is no label.