NoxMail API

Working API documentation

Create temporary inboxes, validate saved inboxes, read messages, verify custom domains, and import inbound email from trusted mail infrastructure. These examples are generated for this live host, not placeholder blog content.

Quick start OpenAPI JSON
Base URL: https://noxmail.app
Current mailbox domain: noxmail.app
Public inbox and custom-domain DNS verification endpoints do not require auth. The inbound import endpoint POST /api/email is server-to-server and requires the worker token.

Quick start that works now

Run these against the live NoxMail host. First create an inbox, then use the returned email and uuid for validation and inbox polling. 

BASE="https://noxmail.app"

# 1) Create a temporary inbox
curl -sS -X POST "$BASE/api/email-box"

# Optional: create on an active custom domain
curl -sS -X POST "$BASE/api/email-box" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

# Response
# {"email":"name.1234@noxmail.app","uuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}
# 2) Validate an email + uuid pair
curl -sS -X POST "$BASE/api/email-box/validate" \
  -H "Content-Type: application/json" \
  -d '{"email":"name.1234@noxmail.app","uuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}'

# Response
# {"is_valid":true}
# 3) Poll inbox messages
curl -sS "$BASE/api/email-box/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/emails"

# Response when empty
# []

Endpoint reference

POST /api/email-box

Create a temporary inbox

Creates a new mailbox and returns the address plus UUID. No request body is required unless you want to request a specific active custom domain.

curl -sS -X POST "https://noxmail.app/api/email-box"
curl -sS -X POST "https://noxmail.app/api/email-box" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

200 response

{
  "email": "arthur11.6091@noxmail.app",
  "uuid": "80d47aee-0585-4e88-acc2-b8bbf7c738b2"
}
POST /api/email-box/validate

Validate a saved inbox

Checks if an email and uuid pair still exists. This is what the frontend uses before reusing a mailbox from local storage.

curl -sS -X POST "https://noxmail.app/api/email-box/validate" \
  -H "Content-Type: application/json" \
  -d '{"email":"arthur11.6091@noxmail.app","uuid":"80d47aee-0585-4e88-acc2-b8bbf7c738b2"}'

200 response

{
  "is_valid": true
}
GET /api/email-box/{emailBoxUuid}/emails

List inbox messages

Returns received message summaries for an inbox UUID. The endpoint also updates the inbox last-accessed timestamp.

curl -sS "https://noxmail.app/api/email-box/80d47aee-0585-4e88-acc2-b8bbf7c738b2/emails"

200 response

[
  {
    "uuid": "message-uuid-here",
    "from": "sender@example.com",
    "real_to": "arthur11.6091@noxmail.app",
    "from_name": "Example Sender",
    "subject": "Hello from NoxMail",
    "received_at": "2026-05-13T10:35:19+00:00"
  }
]
GET /api/email-box/{emailBoxUuid}/email/{emailUuid}

Read one message as JSON

Returns a single message, including the html body. The message is marked as read.

curl -sS "https://noxmail.app/api/email-box/80d47aee-0585-4e88-acc2-b8bbf7c738b2/email/message-uuid-here"

200 response

{
  "uuid": "message-uuid-here",
  "from": "sender@example.com",
  "real_to": "arthur11.6091@noxmail.app",
  "from_name": "Example Sender",
  "subject": "Hello from NoxMail",
  "html": "<p>Message body</p>",
  "received_at": "2026-05-13T10:35:19+00:00"
}
GET /email-box/{emailBoxUuid}/email/{emailUuid}

View one message as HTML

Browser-friendly email rendering route for opening a received message outside the JSON API.

https://noxmail.app/email-box/80d47aee-0585-4e88-acc2-b8bbf7c738b2/email/message-uuid-here
POST /api/custom-domain/setup

Generate custom-domain DNS records

Returns the MX and TXT records needed before NoxMail can activate a domain.

curl -sS -X POST "https://noxmail.app/api/custom-domain/setup" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'
POST /api/custom-domain/verify

Verify and activate a custom domain

Checks MX and TXT DNS records. If both are correct, the domain joins the NoxMail generation pool.

curl -sS -X POST "https://noxmail.app/api/custom-domain/verify" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'
POST /api/email

Import inbound email from a trusted worker

This is not a public client endpoint. Cloudflare Email Worker, Gmail dot-trick sync, or another trusted importer posts parsed mail here. The Authorization header must match CREATE_RECEIVED_EMAIL_API_AUTHORIZATION_KEY. 

curl -sS -X POST "https://noxmail.app/api/email" \
  -H "Authorization: Bearer <CREATE_RECEIVED_EMAIL_API_AUTHORIZATION_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "real_from": "sender@example.com",
    "real_to": "arthur11.6091@noxmail.app",
    "subject": "Hello from API",
    "from_name": "Example Sender",
    "from_address": "sender@example.com",
    "to_multiple": ["arthur11.6091@noxmail.app"],
    "bcc_multiple": [],
    "html": "<p>Hello NoxMail</p>",
    "metadata": {"source":"worker"}
  }'

201 response

"OK"

Operational notes

  • Public inbox endpoints are stateless and use the mailbox UUID as the lookup key.
  • Custom domains require MX @ 10 mx.noxmail.app plus the TXT token generated by Custom Domain.
  • Mail receiving requires trusted importer infrastructure. On this deployment that can be the receive-only SMTP importer, Cloudflare Email Worker, or Gmail dot-trick sync.
  • POST /api/email accepts both raw token and Bearer token authorization formats.
  • POST /api/email only accepts messages for inboxes that already exist in NoxMail.
  • Validation errors return Symfony JSON validation responses; bad worker auth returns 401.
  • OpenAPI JSON is available at https://noxmail.app/api-docs/openapi.json.