Providers and failover

Route mail through your own MTA, AWS SES, Postmark or any SMTP relay with automatic failover.

How failover works

A provider route is one way to deliver mail: your own mail server, AWS SES, Postmark or another SMTP relay. Add more than one and MailForge fails over between them without any change in your code.

  1. For each email, MailForge takes the enabled providers assigned to the email's stream and sorts them by priority (1 first), then by health score.
  2. It tries them in that order. The first provider that accepts the message wins.
  3. A failed attempt lowers the provider's health score by 25. A successful one raises it by 10, up to 100.
  4. Below 30 the provider is rested: 60 seconds at first, 5 minutes once its health reaches 0. After the rest MailForge tries it again by itself. One success puts it back in service, another failure rests it for longer.

A low health score alone never removes a provider. It only moves it behind healthier ones of the same priority. If every provider is resting, the email is still attempted instead of dropped.

The provider that delivered a message is stored on the email as provider_id. Every attempt, including the error a failing provider returned, is written to the event log in the database.

Add a provider

POST/api/v1/providersRequires providers:manage
curl -X POST https://mail.example.com/api/v1/providers \
  -H "Authorization: Bearer $MAILFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AWS SES Frankfurt (fallback)",
    "kind": "aws_ses",
    "priority": 2,
    "streams": [
      "transactional"
    ],
    "config": {
      "region": "eu-central-1",
      "smtpUsername": "AKIA...",
      "smtpPassword": "..."
    }
  }'
Body parameters
namestringrequired
Display name, 2 to 80 characters.
kindstringrequired
own_mta, aws_ses, postmark or custom_smtp.
priorityinteger
1 to 100. Lower is tried first. Defaults to 1.
streamsstring[]
Streams this provider may carry: transactional, marketing or both. Defaults to ["transactional"].
configobject
Connection settings. The keys depend on the kind, see below.
enabledboolean
Defaults to true. Disabled providers are never used.

Response

201 Created
{
  "data": {
    "id": "b1b6f0de-2f55-4f6c-8d0a-5d1c1d7f6a20",
    "name": "AWS SES Frankfurt (fallback)",
    "kind": "aws_ses",
    "priority": 2,
    "streams": [
      "transactional"
    ],
    "enabled": true,
    "health_score": 100,
    "state": "ready",
    "circuit_open_until": null,
    "missing": null,
    "last_error": null,
    "last_success_at": null,
    "last_failure_at": null,
    "created_at": "2026-11-20T18:02:10.004Z",
    "config": {
      "region": "eu-central-1",
      "smtpUsername": "AKIA...",
      "smtpPassword": "••••••••"
    }
  }
}

Secrets in config (pass, smtpPassword, serverToken) are masked in every API response and, when MAILFORGE_ENCRYPTION_KEY is set, encrypted in the database.

StateMeaning
readyEnabled, configured and in service.
restingPaused after repeated failures until circuit_open_until. Retried automatically.
incompleteA required setting is absent. missing says which one.
disabledSwitched off by you.

Provider kinds

KindConfig keysNotes
own_mtahost, port, secure, user, passYour own mail server (KumoMTA, Postfix). Mail from a domain you added is DKIM-signed with that domain's key.
custom_smtphost, port, secure, user, passAny SMTP relay. The relay is responsible for DKIM signing.
aws_sesregion, smtpUsername, smtpPasswordUses the SES SMTP endpoint of the region on port 587. Needs SES SMTP credentials, not IAM access keys.
postmarkserverToken, messageStreamUses the Postmark HTTP API. Without messageStream, transactional mail goes to "outbound" and marketing mail to "broadcast".

List providers

GET/api/v1/providersRequires providers:read

Returns the provider routes of the workspace in failover order under data, each with its current health_score and state. The response also contains catalog, a description of every provider kind and its settings.

curl https://mail.example.com/api/v1/providers \
  -H "Authorization: Bearer $MAILFORGE_API_KEY"
GET/api/v1/providers/{id}Requires providers:read

Returns one provider route.

Test a connection

POST/api/v1/providers/{id}/testRequires providers:manage

Connects to the provider and logs in without sending a message. The request always answers 200. Whether the test passed is in data.ok, and data.message says what to fix when it did not.

curl -X POST https://mail.example.com/api/v1/providers/b1b6f0de-2f55-4f6c-8d0a-5d1c1d7f6a20/test \
  -H "Authorization: Bearer $MAILFORGE_API_KEY"
Response
{
  "data": {
    "ok": true,
    "durationMs": 4,
    "message": "Connection and login succeeded."
  }
}

Change or delete

PATCH/api/v1/providers/{id}Requires providers:manage

Changes only the fields you send: name, priority, streams, enabled or config. A secret that you leave out or send back masked keeps its stored value, so editing a route never wipes its password.

curl -X PATCH https://mail.example.com/api/v1/providers/b1b6f0de-2f55-4f6c-8d0a-5d1c1d7f6a20 \
  -H "Authorization: Bearer $MAILFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": 3,
    "enabled": false
  }'
DELETE/api/v1/providers/{id}Requires providers:manage

Removes the route. Emails that were sent through it keep their history.

curl -X DELETE https://mail.example.com/api/v1/providers/b1b6f0de-2f55-4f6c-8d0a-5d1c1d7f6a20 \
  -H "Authorization: Bearer $MAILFORGE_API_KEY"
Response
{
  "ok": true,
  "id": "b1b6f0de-2f55-4f6c-8d0a-5d1c1d7f6a20"
}