Sending

Send email

Send one transactional email with POST /api/v1/email, the fields it takes, its response, and every error code with its HTTP status.

POST https://app.emailmarketer.io/api/v1/email sends one message. Use it for password resets, receipts, alerts and other email your app sends to one person.

Before you start

  • Verify the sending domain in the app.
  • Create a sender API key for that domain under Transactional, on the domain’s API keys tab.
  • Send from an address on that domain.

Request

curl -X POST https://app.emailmarketer.io/api/v1/email \
  -H "Authorization: Bearer $EM_SENDER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "From": { "name": "Acme", "email": "no-reply@acme.com" },
    "To": [{ "name": "Jane Doe", "email": "jane@example.com" }],
    "ReplyTo": [{ "email": "support@acme.com" }],
    "Subject": "Your receipt for order 1042",
    "ContentType": "html",
    "HTMLContent": "<p>Thanks for your order.</p>",
    "PlainContent": "Thanks for your order.",
    "Tags": ["receipt"]
  }'

Fields

Field Type Required Description
From object Yes { "name", "email" }. The address must be on the key’s domain
To array Yes [{ "name", "email" }]. Up to 10 recipients by default
Subject string Yes Subject line. Also required when you use a template
ContentType string Yes html or plain
HTMLContent string When ContentType is html HTML body
PlainContent string When ContentType is plain Text body. Send it with HTML too, for a text part
CC array No [{ "name", "email" }]. Up to 10 by default
BCC array No [{ "name", "email" }]. Up to 3 by default
ReplyTo array No [{ "name", "email" }]. Up to 5 by default
TemplateID int No Use the body of one of your templates instead of HTMLContent and PlainContent
Attachments array No See Attachments
Headers object No Extra headers, { "X-Order-ID": "1042" }. Header names arrive in lowercase
Tags array No Strings. Tag stats show per domain in the app. Commas split a tag in two
TrackOpens string No "true" turns open tracking on. When omitted, the domain’s setting applies
TrackLinks string No "true" turns link tracking on. When omitted, the domain’s setting applies
ListID, SubscriberID int No Send both to fill merge tags from that subscriber’s fields
IdempotencyKey string No Prevents a duplicate send on retry. See Idempotent sends

Every To, CC and BCC address counts as one email against your monthly allowance.

TrackOpens and TrackLinks cannot turn tracking off for one message. To send without tracking, turn it off on the domain.

Attachments

"Attachments": [
  { "filename": "invoice-1042.pdf", "content": "JVBERi0xLjQK...", "type": "application/pdf", "disposition": "attachment" }
]
Field Description
filename File name the recipient sees
content The file, base64-encoded
type MIME type
disposition attachment

All four fields are required. An attachment that misses one is dropped without an error. Inline images (disposition: "inline" with a content ID) are not supported. Link to hosted images instead.

Response

{ "MessageID": "550e8400-e29b-41d4-a716-446655440000" }

All recipients of one request share one message and one MessageID. Webhooks and the event log use the same ID.

Idempotent sends

A retry after a timeout can send the same email twice. To prevent that, add an IdempotencyKey to the request body:

curl -X POST https://app.emailmarketer.io/api/v1/email \
  -H "Authorization: Bearer $EM_SENDER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "IdempotencyKey": "order-1042-receipt",
    "From": { "name": "Acme", "email": "no-reply@acme.com" },
    "To": [{ "email": "jane@example.com" }],
    "Subject": "Your receipt for order 1042",
    "ContentType": "html",
    "HTMLContent": "<p>Thanks for your order.</p>"
  }'

The emailgateway.sendemail command takes the same IdempotencyKey field. There is no idempotency HTTP header.

  • The key is 1 to 128 characters from A-Z a-z 0-9 . : _ -. Build it from your own event ID, for example order-1042-receipt.
  • A repeat with the same key from the same account and domain within 24 hours sends nothing. It returns the first MessageID with "IdempotentReplay": true.
  • A repeat while the first send is still being processed returns HTTP 409, error 41. Wait and retry.
  • If the check cannot run, the API returns HTTP 503, error 44, and sends nothing. Retry later.

Errors

Errors use HTTP status codes and an Errors array:

{ "Errors": [{ "Code": 14, "Message": "..." }] }
HTTP Code Meaning Retry?
401 13 Missing or invalid sender API key No
403 12 The account is disabled No
403 32 The sending domain is not active No
403 34 The account is not verified No
403 40 The account is not yet approved for transactional sending. Contact us No
404 2 Invalid domain or account No
409 14 A recipient is suppressed (bounced, complained or unsubscribed) No. Mark the address in your app
409 41 A send with this idempotency key is still in progress Yes, after a short wait
422 3 From is missing or invalid No
422 8 Missing Subject or To No
422 9 Missing ContentType No
422 10 Missing HTMLContent No
422 11 Missing PlainContent No
422 15 Invalid TemplateID No
422 18 A recipient’s name or email is missing No
422 19 Invalid recipient email No
422 20 No recipient, or too many No
422 21 to 27 Invalid CC, BCC or From format, or too many CC or BCC recipients No
422 28 to 31 Invalid ReplyTo, or too many No
422 35, 36 Invalid ListID or SubscriberID No
422 42 Invalid idempotency key use No
422 45 The From address is not allowed No
429 17 The account’s send limit for the period is reached Later
429 429 Too many requests Yes, with backoff
503 44 The idempotency check is unavailable. Nothing was sent Yes

Retries

Retry 429, 503, 5xx and timeouts with exponential backoff and an idempotency key. Do not retry 401, 403, 409 (code 14) or 422. They fail the same way again.

Not available

  • Batch sends with different content per recipient. Send one request per message.
  • Scheduled delivery. Messages are sent right away.
  • A test or sandbox mode.