Inbound email

Receive email on your domain as structured JSON.

How inbound works

Your mail server receives mail for inbound.<your-domain>, converts each message to JSON and posts it to the ingest endpoint. MailForge checks the signature, finds the workspace that owns the domain and stores the message. You can then read it in the dashboard or through the API.

Ingest endpoint

POST/api/v1/inboundHMAC signature

This endpoint takes no API key. It is authenticated by an HMAC signature made with the server secret INBOUND_WEBHOOK_SECRET.

Body parameters
fromstringrequired
Sender of the message.
tostring | string[]required
Recipient addresses. The domain of the first address selects the workspace. A leading inbound. is ignored, so support@inbound.acme.com matches the domain acme.com.
subjectstring
Up to 998 characters.
textstring
Plain-text body.
htmlstring
HTML body.
headersobject
Original message headers.
attachmentsarray
Attachment metadata. Stored as you send it.

Response

201 Created
{
  "ok": true,
  "id": "9b2f6c1e-4a7d-4f0b-8c3e-5d6a7b8c9d0e",
  "receivedAt": "2026-11-20T18:10:42.318Z"
}

A wrong or missing signature returns 401. A recipient domain that no workspace owns returns 404.

Signing requests

Compute the HMAC-SHA256 of the exact request body with the secret, hex-encode it and send it in X-MailForge-Signature. The sha256= prefix is optional. Sign the same bytes you send: re-serialising the JSON changes the signature.

BODY='{"from":"Jane <jane@customer.com>","to":"support@inbound.acme.com","subject":"Question about my order","text":"Hi, where is my order?"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$INBOUND_WEBHOOK_SECRET" | sed 's/^.* //')

curl -X POST https://mail.example.com/api/v1/inbound \
  -H "Content-Type: application/json" \
  -H "X-MailForge-Signature: sha256=$SIG" \
  -d "$BODY"

List inbound email

GET/api/v1/inboundRequires inbound:read

Returns the 50 most recent received messages of the workspace.

curl https://mail.example.com/api/v1/inbound \
  -H "Authorization: Bearer $MAILFORGE_API_KEY"
Response
{
  "data": [
    {
      "id": "9b2f6c1e-4a7d-4f0b-8c3e-5d6a7b8c9d0e",
      "from_address": "Jane <jane@customer.com>",
      "to_addresses": [
        "support@inbound.acme.com"
      ],
      "subject": "Question about my order",
      "text_body": "Hi, where is my order?",
      "received_at": "2026-11-20T18:10:42.318Z"
    }
  ]
}

Get one inbound email

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

Returns a single received email under data. To be told when one arrives, subscribe a webhook to inbound.received.