Send an email

Send from the user’s own mailbox, with attachments, custom headers and tracking.

The email goes out through the provider’s SMTP server (Gmail included), from the user’s own address, and lands in their Sent folder.

JSON

curl -X POST "$EE_URL/api/v1/emails" \
  -H "X-API-KEY: $EE_KEY" -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_ba1fa6938d8548298e8ce62e4b4b4e99",
    "to": [{ "display_name": "Ana Lee", "identifier": "[e-mail]" }],
    "cc": ["[e-mail]"],
    "subject": "Proposal",
    "body": "<p>Hi Ana,</p><p>Here is the proposal.</p>",
    "attachments": [{ "filename": "proposal.pdf", "content_type": "application/pdf", "content": "JVBERi0xLjQK…" }]
  }'

With curl, use --form-string for HTML bodies: -F 'body=<p>…' treats a value starting with < as a file name.

Fields

account_id · string · required

The account to send from (acc_…).

to, cc, bcc · attendee[]

Recipients as [{ "display_name": "Ana", "identifier": "[e-mail]" }], a list of addresses, or one comma-separated string. At least one recipient is required (except for replies).

subject · string

body · string

HTML body. A text version is made from it automatically.

body_plain · string

Plain-text body, if you want to set it yourself.

from · attendee

display_name changes the sender’s name. identifier sends from an alias; the provider must allow it (a Gmail “Send mail as” address, for example).

reply_to · string

The email_… id of an email to answer. See Replies and threads.

reply_to_addresses · attendee[]

Addresses for the Reply-To header.

custom_headers · object[]

[{ "name": "X-Campaign", "value": "q4" }]. Allowed: any X-… header, List-Unsubscribe, List-Unsubscribe-Post, and Reply-To. Content-Type is accepted and ignored.

tracking_options · object

{ "opens": true, "links": true, "label": "…" }. See Tracking.

attachments · file[] | object[]

Multipart: files in fields named attachments. JSON: [{ "filename", "content_type", "content" }] with content in base64.

In a multipart request, send to, cc, bcc, tracking_options and custom_headers as JSON text.

Requests are limited to 30 MB in total, attachments included. Providers have their own limits, for example 25 MB for Gmail.

Response

201 Created

{
  "object": "EmailSent",
  "account_id": "acc_ba1fa6938d8548298e8ce62e4b4b4e99",
  "message_id": "[e-mail]",
  "provider_id": null,
  "tracking_id": null
}

• message_id identifies the email in every mailbox it reaches. Its Sent copy has the same message_id.
• provider_id is null: SMTP doesn’t return an id when sending. The Sent copy gets its ids when it syncs.
• tracking_id is a trk_… id when you use tracking_options, otherwise null.
• The Sent copy syncs a moment later, and you receive an email.new event with the full email and origin: "api".

Error	When
400 errors/invalid_parameters	A field is wrong, for example no recipient, or account_id isn’t an acc_… id
401 errors/invalid_credentials	The provider rejected the account’s credentials. Reconnect it
404 errors/not_found	No account with this id
422 errors/provider_rejected	The provider refused the email, for example because it’s too large
502 errors/provider_error	The provider failed or didn’t answer

If a send request times out on your side, don’t retry blindly: the email may already be on its way. Check the Sent folder (GET /api/v1/emails?account_id=acc_…&role=SENT) for the message_id first.