Appearance

Messages ​

Fetch, read, and delete emails. All endpoints require authentication and an account ID in the URL path.

All message endpoints use the pattern:

/api/accounts/{account_id}/messages

List Messages ​

GET /api/accounts/{account_id}/messages

Returns a paginated list of emails.

Parameters:

NameInTypeDefaultDescription
account_idpathuuid—Account ID
pagequeryinteger1Page number

Response (200):

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

Pagination: 30 messages per page. If the response contains fewer than 30 messages, you've reached the last page.

Get a Message ​

GET /api/accounts/{account_id}/messages/{id}

Returns the full message content including body and attachments.

Response (200):

json
{
  "id": "f5e6d7c8-...",
  "sender": "noreply@example.com",
  "from": "Example <noreply@example.com>",
  "subject": "Verify your email",
  "address": "demo@mail.td",
  "size": 4523,
  "created_at": "2025-01-15T10:30:00Z",
  "text_body": "Click the link below to verify your email...",
  "html_body": "<html>...</html>",
  "attachments": [
    {
      "index": 0,
      "filename": "document.pdf",
      "content_type": "application/pdf",
      "size": 12345
    }
  ]
}

Errors: 404 if not found, 410 if expired.

Delete a Message ​

DELETE /api/accounts/{account_id}/messages/{id}

Soft-deletes an email and reclaims storage quota.

Response: 204 No Content

Download Raw Source ​

GET /api/accounts/{account_id}/messages/{id}/source

Downloads the raw RFC 822 .eml file.

Response (200): Content-Type: message/rfc822 with Content-Disposition: attachment; filename="message.eml"

Download Attachment ​

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

Downloads a specific attachment by its index.

NameInTypeDescription
idpathuuidMessage ID
indexpathintegerAttachment index (from message detail)

Response (200): Binary content with appropriate Content-Type and Content-Disposition headers.

Errors: 400 if invalid index, 404 if not found, 410 if expired.

Mark as Read ​

PUT /api/accounts/{account_id}/messages/{id}/read

Marks a single message as read. Idempotent.

Response: 204 No Content

Batch Mark as Read ​

PUT /api/accounts/{account_id}/messages/read

Marks multiple messages as read, or all messages.

Request (specific IDs):

json
{
  "ids": ["id1", "id2", "id3"]
}

Request (mark all):

json
{
  "all": true
}

Response (200):

json
{
  "updated": 5
}

Maximum 200 IDs per request.

Mail.td API Documentation