Emails
Send email now or later, send in batches, and read the status and timeline of every message.
Send an email
/api/v1/emailsRequires emails:sendValidates the message, stores it in the database and puts it on the delivery queue. The response comes back before the mail is handed to a provider.
curl -X POST https://mail.example.com/api/v1/emails \
-H "Authorization: Bearer $MAILFORGE_API_KEY" \
-H "Idempotency-Key: order-94821-confirmation" \
-H "Content-Type: application/json" \
-d '{
"from": "Acme <orders@acme.com>",
"to": [
"customer@example.com"
],
"replyTo": "support@acme.com",
"subject": "Order 94821 confirmed",
"html": "<h1>Thanks for your order</h1><p>We will email you when it ships.</p>",
"text": "Thanks for your order. We will email you when it ships.",
"tags": {
"category": "order-confirmation",
"orderId": "94821"
}
}'fromstringrequired- Sender, as
orders@acme.comorAcme <orders@acme.com>. Use an address on a domain you added so the mail is DKIM-signed. tostring | string[]required- One address or up to 50. Addresses are lower-cased and de-duplicated.
subjectstringrequired- 1 to 998 characters.
htmlstring- HTML body, up to 2,000,000 characters. At least one of
htmlortextis required. textstring- Plain-text body, up to 2,000,000 characters.
ccstring | string[]- Up to 50 addresses.
bccstring | string[]- Up to 50 addresses.
replyTostring- Reply-To address.
scheduledAtstring- ISO 8601 time with offset, for example
2026-12-01T09:00:00Z, up to 30 days ahead. See Schedule and cancel. stream"transactional" | "marketing"- Defaults to
transactional. A provider only receives mail for the streams it is assigned to, so you can keep marketing mail off your transactional IPs. tagsobject- String key/value pairs stored with the email and returned when you read it. A list of
{ name, value }pairs is accepted as well. headersobject- Custom headers added to the message when it is sent over SMTP (own MTA, custom SMTP, AWS SES).
idempotencyKeystring- 8 to 128 characters. Same effect as the
Idempotency-Keyheader. The body field wins if both are set. preferredProviderIdstring- Id of a provider route to try first. The other providers stay available as fallback.
The snake_case spellings reply_to, scheduled_at, idempotency_key and preferred_provider_id are accepted too, so a request written for Resend works after you change the URL and the key.
Response
{
"id": "f59aee24-ea49-48d1-92b1-b0c510ce02d4",
"status": "queued",
"stream": "transactional",
"recipients": 1,
"scheduledAt": null,
"queuedInRedis": true,
"spamCheck": {
"score": 0.8,
"verdict": "good",
"rules": [
"MISSING_TEXT_PART"
]
}
}Once you have a 202, the email is safe in the database. queuedInRedis is false when Redis could not be reached at that moment. The email is still sent: the worker looks for waiting emails every 15 seconds and picks it up.
spamCheck is the result of the pre-send content check. By default it only reports. The response also carries RateLimit-* and X-Quota-* headers, described under Errors.
To reuse the same content with different values, store it as a template and send that instead.
Schedule and cancel
Set scheduledAt to send later. The email gets the status scheduled and is sent at that time. A time in the past means now. More than 30 days ahead is refused with 422.
curl -X POST https://mail.example.com/api/v1/emails \
-H "Authorization: Bearer $MAILFORGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "Acme <news@acme.com>",
"to": "customer@example.com",
"subject": "Your trial ends tomorrow",
"text": "Upgrade today to keep your projects.",
"scheduledAt": "2026-12-01T09:00:00Z"
}'/api/v1/emails/{id}/cancelRequires emails:sendCancels an email that is still scheduled.
curl -X POST https://mail.example.com/api/v1/emails/6b33260f-bd4e-4095-99e3-cea0013ba145/cancel \
-H "Authorization: Bearer $MAILFORGE_API_KEY"{
"id": "6b33260f-bd4e-4095-99e3-cea0013ba145",
"status": "canceled"
}An email that is no longer scheduled cannot be recalled. The request then returns 409 with the code not_cancelable.
Send a batch
/api/v1/emails/batchRequires emails:sendSends up to 100 emails with one request. The body is an array of email objects with the same fields as a single send. An object of the form { emails: [...] } works too.
curl -X POST https://mail.example.com/api/v1/emails/batch \
-H "Authorization: Bearer $MAILFORGE_API_KEY" \
-H "Content-Type: application/json" \
-d '[
{
"from": "Acme <orders@acme.com>",
"to": "ada@example.com",
"subject": "Your invoice for November",
"text": "Hi Ada, your invoice is ready."
},
{
"from": "Acme <orders@acme.com>",
"to": "grace@example.com",
"subject": "Your invoice for November",
"text": "Hi Grace, your invoice is ready."
}
]'{
"data": [
{
"id": "47c43b16-e185-401a-9b30-630c78340da2",
"status": "queued",
"scheduledAt": null,
"spamCheck": {
"score": 0,
"verdict": "good",
"rules": []
}
},
{
"id": "e1b80724-85e7-4139-b80f-2ffd8ebc0eff",
"status": "queued",
"scheduledAt": null,
"spamCheck": {
"score": 0,
"verdict": "good",
"rules": []
}
}
]
}A batch is all or nothing. If one email is invalid, nothing is sent and details lists the problems by position in the array.
{
"error": "Email 1: to: Must be a valid address like 'user@example.com' or 'Name <user@example.com>'. Nothing was sent.",
"code": "validation_error",
"details": {
"1": [
"to: Must be a valid address like 'user@example.com' or 'Name <user@example.com>'.",
"html: Either 'html' or 'text' body must be provided."
]
}
}Idempotency
Send an Idempotency-Key header (or the idempotencyKey body field) to make retries safe. If a key was already used in your workspace, MailForge does not send again and returns the original email id with 200.
{
"id": "f59aee24-ea49-48d1-92b1-b0c510ce02d4",
"status": "sent",
"stream": "transactional",
"recipients": 1,
"scheduledAt": null,
"queuedInRedis": true,
"deduplicated": true
}Keys do not expire, so use one that is unique per message, such as order-94821-confirmation.
Delivery and retries
The worker picks each queued email and does the following:
- Removes recipients on your suppression list. If every recipient is suppressed, the email ends as
suppressedand nothing is sent. - Builds the failover chain from your providers for the email's stream, ordered by priority and health.
- Tries each provider in order until one accepts the message. The provider that accepted it is stored on the email.
What happens after a failure depends on whose fault it was:
| Failure | Example | What MailForge does |
|---|---|---|
| Provider | Connection refused, login failed, rate limit | Tries the next provider. If none works, retries later: up to 8 attempts with growing pauses, starting at 5 seconds. |
| Recipient | 550 5.1.1 User unknown | Hard bounce. No retry and no other provider. The email ends as bounced and the address goes on the suppression list. |
| Message | Too large, rejected by policy | No retry. The email ends as failed. |
Before sending, links in HTML bodies are rewritten and an open pixel is added, unless you switched tracking off for the domain.
Mail sent over SMTP carries the headers X-MailForge-Id (the email id) and X-MailForge-Stream. To be told about each outcome, add a webhook.
List emails
/api/v1/emailsRequires emails:readReturns the emails of your workspace, newest first, 50 per page unless you ask otherwise.
curl "https://mail.example.com/api/v1/emails?status=sent&limit=2" \
-H "Authorization: Bearer $MAILFORGE_API_KEY"limitinteger- 1 to 100. Defaults to 50.
cursorstring- The
nextCursorof the previous page. statusstring- Only emails with this status.
streamstringtransactionalormarketing.qstring- Search text, for example a recipient address or part of the subject.
{
"data": [
{
"id": "e1b80724-85e7-4139-b80f-2ffd8ebc0eff",
"stream": "transactional",
"from_address": "orders@acme.com",
"to_addresses": [
"grace@example.com"
],
"subject": "Your invoice for November",
"status": "sent",
"provider_id": "73e85b67-0a31-4b80-91e2-46a9b64608f9",
"provider_message_id": "<7a69114a-6b9c-b601-c436-0d97217111a8@acme.com>",
"tags": {},
"attempts": 1,
"last_error": null,
"test_mode": false,
"created_at": "2026-11-20T20:02:25.590Z",
"scheduled_at": null,
"sent_at": "2026-11-20T20:02:25.617Z"
}
],
"nextCursor": "MjAyNi0xMS0yMCAyMDowMjoyNS41OTAzMTIrMDB8NDdjNDNiMTY"
}Pass nextCursor as cursor to get the next page. It is null on the last page.
Get one email
/api/v1/emails/{id}Requires emails:readReturns the full message with its content and, in events, everything that happened to it in order.
curl https://mail.example.com/api/v1/emails/e1b80724-85e7-4139-b80f-2ffd8ebc0eff \
-H "Authorization: Bearer $MAILFORGE_API_KEY"{
"data": {
"id": "e1b80724-85e7-4139-b80f-2ffd8ebc0eff",
"stream": "transactional",
"from_address": "orders@acme.com",
"to_addresses": [
"grace@example.com"
],
"cc_addresses": [],
"bcc_addresses": [],
"reply_to": null,
"subject": "Your invoice for November",
"html_body": null,
"text_body": "Hi Grace, your invoice is ready.",
"headers": {},
"tags": {},
"status": "sent",
"provider_id": "73e85b67-0a31-4b80-91e2-46a9b64608f9",
"provider_name": "Primary MTA",
"provider_kind": "own_mta",
"provider_message_id": "<7a69114a-6b9c-b601-c436-0d97217111a8@acme.com>",
"idempotency_key": null,
"attempts": 1,
"last_error": null,
"test_mode": false,
"created_at": "2026-11-20T20:02:25.590Z",
"scheduled_at": null,
"sent_at": "2026-11-20T20:02:25.617Z",
"events": [
{
"id": "fdb511f7-2595-4b00-882f-5ff112ce595c",
"event_type": "queued",
"payload": {},
"occurred_at": "2026-11-20T20:02:25.590Z"
},
{
"id": "f6c0fb9a-fc05-4b1b-921c-61dcbac9247f",
"event_type": "sent",
"payload": {
"attempt": 1,
"provider": "Primary MTA",
"providerId": "73e85b67-0a31-4b80-91e2-46a9b64608f9",
"dkimSigned": true,
"providerMessageId": "<7a69114a-6b9c-b601-c436-0d97217111a8@acme.com>",
"attempts": [
{
"ok": true,
"durationMs": 5,
"providerId": "73e85b67-0a31-4b80-91e2-46a9b64608f9",
"providerName": "Primary MTA"
}
]
},
"occurred_at": "2026-11-20T20:02:25.618Z"
}
]
}
}Status values
| Status | Meaning |
|---|---|
queued | Accepted and waiting for a worker, also while it waits for a retry. |
scheduled | Accepted with a future scheduledAt. |
sending | A worker is handing it to a provider right now. |
sent | A provider accepted the message. |
delivered | The receiving server confirmed delivery. This needs feedback from the mail server, so most emails stay at sent. |
bounced | The recipient address was permanently rejected. |
complained | The recipient marked the message as spam. |
failed | Every provider and every retry failed, or the message itself was refused. |
suppressed | Every recipient is on the suppression list. Nothing was sent. |
canceled | A scheduled email was canceled before it was sent. |