Emails

Send email now or later, send in batches, and read the status and timeline of every message.

Send an email

POST/api/v1/emailsRequires emails:send

Validates 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"
    }
  }'
Body parameters
fromstringrequired
Sender, as orders@acme.com or Acme <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 html or text is 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-Key header. 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

202 Accepted
{
  "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"
  }'
POST/api/v1/emails/{id}/cancelRequires emails:send

Cancels 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"
Response
{
  "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

POST/api/v1/emails/batchRequires emails:send

Sends 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."
    }
  ]'
202 Accepted
{
  "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.

422 Unprocessable Entity
{
  "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.

200 OK (duplicate)
{
  "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:

  1. Removes recipients on your suppression list. If every recipient is suppressed, the email ends as suppressed and nothing is sent.
  2. Builds the failover chain from your providers for the email's stream, ordered by priority and health.
  3. 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:

FailureExampleWhat MailForge does
ProviderConnection refused, login failed, rate limitTries the next provider. If none works, retries later: up to 8 attempts with growing pauses, starting at 5 seconds.
Recipient550 5.1.1 User unknownHard bounce. No retry and no other provider. The email ends as bounced and the address goes on the suppression list.
MessageToo large, rejected by policyNo 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

GET/api/v1/emailsRequires emails:read

Returns 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"
Query parameters
limitinteger
1 to 100. Defaults to 50.
cursorstring
The nextCursor of the previous page.
statusstring
Only emails with this status.
streamstring
transactional or marketing.
qstring
Search text, for example a recipient address or part of the subject.
Response
{
  "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

GET/api/v1/emails/{id}Requires emails:read

Returns 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"
Response
{
  "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

StatusMeaning
queuedAccepted and waiting for a worker, also while it waits for a retry.
scheduledAccepted with a future scheduledAt.
sendingA worker is handing it to a provider right now.
sentA provider accepted the message.
deliveredThe receiving server confirmed delivery. This needs feedback from the mail server, so most emails stay at sent.
bouncedThe recipient address was permanently rejected.
complainedThe recipient marked the message as spam.
failedEvery provider and every retry failed, or the message itself was refused.
suppressedEvery recipient is on the suppression list. Nothing was sent.
canceledA scheduled email was canceled before it was sent.