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 exampleorder-1042-receipt. - A repeat with the same key from the same account and domain within 24 hours sends nothing. It returns the first
MessageIDwith"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.