Quickstart
Run MailForge, create an API key and send your first email in a few minutes.
Overview
MailForge is an email platform you host yourself. It gives you a REST API and a dashboard for sending email through your own mail server, with automatic failover to AWS SES, Postmark or any SMTP relay when a provider fails.
Every endpoint lives under /api/v1 on your own domain. The examples in these docs use https://mail.example.com as a placeholder for it.
1. Run MailForge
You need Node.js 22 or newer and Docker. The compose file starts PostgreSQL, Redis and Mailpit, a local mail catcher that stands in for a real mail server during development.
npm install
npm run docker:up # PostgreSQL, Redis, Mailpit
npm run dev:web # API and dashboard on http://localhost:3000
npm run dev:worker # delivery worker (second terminal)Details and the production setup are on the self-hosting page.
2. Create a workspace
Open /login, choose New Workspace and register. The first user owns the workspace and gets every permission. MailForge also creates a first provider route that points at the mail server from your environment (MTA_SMTP_HOST), so you can send right away.
3. Create an API key
In the dashboard, open API Keys and create a key. The full key is shown once, so copy it immediately. Choose a live key for this guide: it starts with mf_live_. Keys that start with mf_test_ run everything but never send real email.
export MAILFORGE_API_KEY="mf_live_..."4. Send an email
curl -X POST https://mail.example.com/api/v1/emails \
-H "Authorization: Bearer $MAILFORGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "Acme <hello@acme.com>",
"to": "customer@example.com",
"subject": "Welcome to Acme",
"html": "<p>Your account is ready.</p>"
}'The API answers with 202 Accepted as soon as the message is stored and queued. Delivery happens in the worker.
{
"id": "f59aee24-ea49-48d1-92b1-b0c510ce02d4",
"status": "queued",
"stream": "transactional",
"recipients": 1,
"scheduledAt": null,
"queuedInRedis": true,
"spamCheck": {
"score": 0,
"verdict": "good",
"rules": []
}
}Next steps
- Use the Node.js or Python SDK instead of raw HTTP.
- Create a template and send it with variables.
- Add your domain and publish the DKIM, SPF and DMARC records.
- Add a second provider so mail keeps flowing when the first one fails.
- Add a webhook to hear about bounces and failures.
- Use a test key in CI so no real email leaves the server.
- Restrict API keys to the permissions each service needs.