List and get messages | TuskMail API

The message object

Message (list item)

{
  "id": "Mabc123",
  "thread_id": "Tabc123",
  "folder_ids": ["b1"],
  "from": [{ "name": "Amina Wanjiru", "email": "[email protected]" }],
  "to": [{ "name": "", "email": "[email protected]" }],
  "cc": [],
  "subject": "Quote request for Q4 deliveries",
  "received_at": "2025-01-15T18:45:00Z",
  "preview": "Hello, could you share your latest rates...",
  "is_read": false,
  "is_starred": false,
  "has_attachment": true,
  "size": 48213,
  "attachments": [
    { "attachment_id": "B987", "name": "rates.pdf", "type": "application/pdf", "size": 40960 }
  ]
}

Name	Type	Description
`id`	string	Message id.
`thread_id`	string	Conversation thread id.
`folder_ids`	string[]	Folders the message is in.
`from / to / cc`	address[]	Arrays of `{ "name", "email" }`.
`subject`	string	Subject line.
`received_at`	string	ISO 8601 timestamp.
`preview`	string	Short plain-text preview.
`is_read / is_starred`	boolean	Flags.
`has_attachment`	boolean	Whether the message has attachments.
`size`	integer	Size in bytes.
`attachments`	object[]	`attachment_id`, `name`, `type`, `size`.
`bcc, html, text, message_id`	various	Only on the single-message GET.

List messages

GET/v1/messages

Name	Type	Description
`folder`	string	A role (`inbox`, `sent`, `drafts`, `junk`, `trash`) or a folder id. Omit to search all folders.
`q`	string	Search text.
`unread`	boolean	Only unread messages.
`starred`	boolean	Only starred messages.
`limit`	integer	1 to 100. Default 25.
`position`	integer	Offset for paging. Default 0.

curl "https://api.tuskmail.africa/v1/messages?folder=inbox&unread=true&limit=10" \
  -H "X-API-Key: $TK_API_KEY" \
  -u "$MAILBOX_EMAIL:$APP_PASSWORD"

200 OK

{
  "data": [
    {
      "id": "Mabc123",
      "thread_id": "Tabc123",
      "folder_ids": ["b1"],
      "from": [{ "name": "Amina Wanjiru", "email": "[email protected]" }],
      "to": [{ "name": "", "email": "[email protected]" }],
      "cc": [],
      "subject": "Quote request for Q4 deliveries",
      "received_at": "2025-01-15T18:45:00Z",
      "preview": "Hello, could you share your latest rates...",
      "is_read": false,
      "is_starred": false,
      "has_attachment": true,
      "size": 48213,
      "attachments": [
        { "attachment_id": "B987", "name": "rates.pdf", "type": "application/pdf", "size": 40960 }
      ]
    }
  ],
  "total": 6,
  "limit": 10,
  "position": 0,
  "next_position": null
}

See Pagination for paging through large result sets.

Retrieve a message

GET/v1/messages/{id}

Name	Type	Description
`id`required	string	Message id, in the path.
`mark_read`	boolean	If true, the message is also marked read.

curl "https://api.tuskmail.africa/v1/messages/Mabc123?mark_read=true" \
  -H "X-API-Key: $TK_API_KEY" \
  -u "$MAILBOX_EMAIL:$APP_PASSWORD"

200 OK (additional fields)

{
  "id": "Mabc123",
  "subject": "Quote request for Q4 deliveries",
  "bcc": [],
  "text": "Hello, could you share your latest rates...",
  "html": "<p>Hello, could you share your latest rates...</p>",
  "message_id": "<[email protected]>",
  "...": "all other fields as in the message object"
}

An unknown id returns 404 not_found.