NoxMail API

Working API documentation

Create temporary inboxes, validate saved inboxes, read messages, and import inbound email from a trusted worker. These examples are generated for this live host, not placeholder blog content.

Quick start OpenAPI JSON
Base URL: https://www.noxmail.app
Current mailbox domain: www.noxmail.app
Public inbox 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://www.noxmail.app"

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

# Response
# {"email":"name.1234@www.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@www.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.

curl -sS -X POST "https://www.noxmail.app/api/email-box"

200 response

{
  "email": "arthur11.6091@www.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://www.noxmail.app/api/email-box/validate" \
  -H "Content-Type: application/json" \
  -d '{"email":"arthur11.6091@www.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://www.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@www.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://www.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@www.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://www.noxmail.app/email-box/80d47aee-0585-4e88-acc2-b8bbf7c738b2/email/message-uuid-here
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://www.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@www.noxmail.app",
    "subject": "Hello from API",
    "from_name": "Example Sender",
    "from_address": "sender@example.com",
    "to_multiple": ["arthur11.6091@www.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.
  • Mail receiving requires an importer. On this deployment that means Cloudflare Email Worker or Gmail dot-trick sync, not direct SMTP on port 25.
  • POST /api/email accepts both raw token and Bearer token authorization formats.
  • Validation errors return Symfony JSON validation responses; bad worker auth returns 401.
  • OpenAPI JSON is available at https://www.noxmail.app/api-docs/openapi.json.