Appearance

Messages ​

Fetch, read, and delete emails. All endpoints require authentication.

List Messages ​

GET /api/messages

Returns a paginated list of messages in the mailbox (30 messages per page).

Parameters ​

NameInTypeDefaultDescription
pagequeryinteger1Page number (≥ 1)

Pagination ​

  • Each page returns up to 30 messages, ordered by newest first
  • If fewer than 30 messages are returned, you've reached the last page
  • There is no total field — check if the returned count is less than 30 to stop paginating

Request ​

bash
curl https://api.mail.cx/api/messages?page=1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 ​

json
{
  "messages": [
    {
      "id": "f5e6d7c8-a1b2-3c4d-e5f6-789012345678",
      "sender": "noreply@example.com",
      "from": "Example Service <noreply@example.com>",
      "subject": "Verify your email address",
      "preview_text": "Click the link below to verify your email...",
      "size": 4523,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "page": 1
}

Message Summary Fields ​

FieldTypeDescription
iduuidMessage ID
senderstringEnvelope sender address
fromstringFrom header (display name + address)
subjectstringSubject line
preview_textstringFirst ~100 characters of the message body
sizeintegerMessage size in bytes
created_atstringReceived timestamp (ISO 8601)

Get a Message ​

GET /api/messages/{id}

Returns the full message content including HTML body and attachments.

Request ​

bash
curl https://api.mail.cx/api/messages/f5e6d7c8-a1b2-3c4d-e5f6-789012345678 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 ​

json
{
  "id": "f5e6d7c8-a1b2-3c4d-e5f6-789012345678",
  "sender": "noreply@example.com",
  "from": "Example Service <noreply@example.com>",
  "subject": "Verify your email address",
  "address": "demo@mail.cx",
  "size": 4523,
  "created_at": "2025-01-15T10:30:00Z",
  "text_body": "Click the link below to verify your email:\nhttps://example.com/verify?token=abc123",
  "html_body": "<html><body><p>Click the link below...</p></body></html>",
  "attachments": [
    {
      "index": 0,
      "filename": "receipt.pdf",
      "content_type": "application/pdf",
      "size": 24680
    }
  ]
}

Full Message Fields ​

FieldTypeDescription
iduuidMessage ID
senderstringEnvelope sender address
fromstringFrom header
subjectstringSubject line
addressstringRecipient address (your mailbox)
sizeintegerMessage size in bytes
created_atstringReceived timestamp
text_bodystring?Plain text body (null if not present)
html_bodystring?HTML body (null if not present)
attachmentsarrayList of attachments

Attachment Fields ​

FieldTypeDescription
indexintegerAttachment index (for download)
filenamestringOriginal file name
content_typestringMIME type
sizeintegerSize in bytes

Errors ​

StatusError CodeDescription
404not_foundMessage does not exist
410expiredMessage has expired

Delete a Message ​

DELETE /api/messages/{id}

Request ​

bash
curl -X DELETE https://api.mail.cx/api/messages/f5e6d7c8-... \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 204 ​

No content. Message has been deleted.

Download Raw Source ​

GET /api/messages/{id}/source

Download the raw EML (RFC 822) source of an email. Useful for debugging or archival.

Request ​

bash
curl https://api.mail.cx/api/messages/f5e6d7c8-.../source \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o email.eml

Response 200 ​

Returns the raw email source with Content-Type: message/rfc822.

Download Attachment ​

GET /api/messages/{id}/attachments/{index}

Download a specific attachment by its index.

Parameters ​

NameInTypeDescription
idpathuuidMessage ID
indexpathintegerAttachment index (from message detail)

Request ​

bash
curl https://api.mail.cx/api/messages/f5e6d7c8-.../attachments/0 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o receipt.pdf

Response 200 ​

Returns the attachment binary with appropriate Content-Type and Content-Disposition headers.

Errors ​

StatusError CodeDescription
400invalid_indexIndex out of range
404not_foundMessage not found
410expiredMessage has expired

Mail.cx API Documentation