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.

Terminal
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.

Terminal
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.

Response
{
  "id": "f59aee24-ea49-48d1-92b1-b0c510ce02d4",
  "status": "queued",
  "stream": "transactional",
  "recipients": 1,
  "scheduledAt": null,
  "queuedInRedis": true,
  "spamCheck": {
    "score": 0,
    "verdict": "good",
    "rules": []
  }
}

Next steps