API Documentation

Internal API reference for TramSangTao Mail. All endpoints return JSON unless otherwise stated. Base URL: http://mail.tramfast.com

Email Box

Create, look up and validate temporary email boxes.

POST /api/email-box

Create a new random temporary email box.

Response (200/201)

{
    "email": "fluffy.kitten.4821@example.com",
    "uuid": "0193e0a9-1a0b-7b9b-a0f1-9f1c8a2c8c4d"
}

cURL

curl -X POST http://mail.tramfast.com/api/email-box
POST /api/email-box/custom

Find or create a mailbox by custom name. Re-using the same name returns the same mailbox.

Note: Name: 1-64 chars, letters / digits / "." / "_" / "-". Domain is fixed to the first active domain.

Request body

{
    "name": "team-alpha"
}

Response (200/201)

{
    "email": "team-alpha@example.com",
    "uuid": "0193e0a9-1a0b-7b9b-a0f1-9f1c8a2c8c4d"
}

cURL

curl -X POST http://mail.tramfast.com/api/email-box/custom \
  -H 'Content-Type: application/json' \
  -d '{"name":"team-alpha"}'
POST /api/email-box/validate

Validate an email + uuid pair (used to verify a mailbox saved in localStorage still exists).

Request body

{
    "email": "team-alpha@example.com",
    "uuid": "0193e0a9-1a0b-7b9b-a0f1-9f1c8a2c8c4d"
}

Response (200/201)

{
    "is_valid": true
}

cURL

curl -X POST http://mail.tramfast.com/api/email-box/validate \
  -H 'Content-Type: application/json' \
  -d '{"email":"team-alpha@example.com","uuid":"<uuid>"}'

Messages

List and read received messages of a mailbox.

GET /api/email-box/{emailBoxUuid}/emails

List all messages received by a mailbox. Marks all subjects as read.

Response (200/201)

[
    {
        "uuid": "0193e0a9-1a0b-7b9b-a0f1-9f1c8a2c8c4d",
        "from": "sender@partner.com",
        "real_to": "team-alpha@example.com",
        "from_name": "Sender",
        "subject": "Welcome!",
        "received_at": "2026-05-15T10:30:00+00:00"
    }
]

cURL

curl http://mail.tramfast.com/api/email-box/<emailBoxUuid>/emails
GET /api/email-box/{emailBoxUuid}/email/{emailUuid}

Get the full content of a single message (HTML body included). Marks the message as read.

Response (200/201)

{
    "uuid": "0193e0a9-1a0b-7b9b-a0f1-9f1c8a2c8c4d",
    "from": "sender@partner.com",
    "real_to": "team-alpha@example.com",
    "from_name": "Sender",
    "subject": "Welcome!",
    "html": "<p>Hello!</p>",
    "received_at": "2026-05-15T10:30:00+00:00"
}

cURL

curl http://mail.tramfast.com/api/email-box/<emailBoxUuid>/email/<emailUuid>
GET /email-box/{emailBoxUuid}/email/{emailUuid}

Render a single message as an HTML page (used by the "View Full Screen" button).

Response (200/201)

<HTML page>

cURL

curl http://mail.tramfast.com/email-box/<emailBoxUuid>/email/<emailUuid>

Inbound (webhook)

Used by the SMTP gateway to deliver incoming mail into the system.

POST /api/email auth required

Webhook endpoint that ingests an incoming email.

Note: Protected by CreateReceivedEmailAuthValidator – requires the gateway auth header.

Request body

{
    "real_from": "sender@partner.com",
    "real_to": "team-alpha@example.com",
    "subject": "Welcome!",
    "from_name": "Sender",
    "from_address": "sender@partner.com",
    "to_multiple": [
        "team-alpha@example.com"
    ],
    "bcc_multiple": null,
    "html": "<p>Hello!</p>",
    "metadata": null
}

Response (200/201)

"OK"

cURL

curl -X POST http://mail.tramfast.com/api/email \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <gateway-token>' \
  -d '{...}'