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.
- 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. - It tries them in that order. The first provider that accepts the message wins.
- A failed attempt lowers the provider's health score by 25. A successful one raises it by 10, up to 100.
- 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
/api/v1/providersRequires providers:managecurl -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": "..."
}
}'namestringrequired- Display name, 2 to 80 characters.
kindstringrequiredown_mta,aws_ses,postmarkorcustom_smtp.priorityinteger- 1 to 100. Lower is tried first. Defaults to 1.
streamsstring[]- Streams this provider may carry:
transactional,marketingor 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
{
"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.
| State | Meaning |
|---|---|
ready | Enabled, configured and in service. |
resting | Paused after repeated failures until circuit_open_until. Retried automatically. |
incomplete | A required setting is absent. missing says which one. |
disabled | Switched off by you. |
Provider kinds
| Kind | Config keys | Notes |
|---|---|---|
own_mta | host, port, secure, user, pass | Your own mail server (KumoMTA, Postfix). Mail from a domain you added is DKIM-signed with that domain's key. |
custom_smtp | host, port, secure, user, pass | Any SMTP relay. The relay is responsible for DKIM signing. |
aws_ses | region, smtpUsername, smtpPassword | Uses the SES SMTP endpoint of the region on port 587. Needs SES SMTP credentials, not IAM access keys. |
postmark | serverToken, messageStream | Uses the Postmark HTTP API. Without messageStream, transactional mail goes to "outbound" and marketing mail to "broadcast". |
List providers
/api/v1/providersRequires providers:readReturns 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"/api/v1/providers/{id}Requires providers:readReturns one provider route.
Test a connection
/api/v1/providers/{id}/testRequires providers:manageConnects 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"{
"data": {
"ok": true,
"durationMs": 4,
"message": "Connection and login succeeded."
}
}Change or delete
/api/v1/providers/{id}Requires providers:manageChanges 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
}'/api/v1/providers/{id}Requires providers:manageRemoves 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"{
"ok": true,
"id": "b1b6f0de-2f55-4f6c-8d0a-5d1c1d7f6a20"
}