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
/api/v1/inboundHMAC signatureThis endpoint takes no API key. It is authenticated by an HMAC signature made with the server secret INBOUND_WEBHOOK_SECRET.
fromstringrequired- Sender of the message.
tostring | string[]required- Recipient addresses. The domain of the first address selects the workspace. A leading
inbound.is ignored, sosupport@inbound.acme.commatches the domainacme.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
{
"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
/api/v1/inboundRequires inbound:readReturns the 50 most recent received messages of the workspace.
curl https://mail.example.com/api/v1/inbound \
-H "Authorization: Bearer $MAILFORGE_API_KEY"{
"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
/api/v1/inbound/{id}Requires inbound:readReturns a single received email under data. To be told when one arrives, subscribe a webhook to inbound.received.