List mailbox messages

curl --request GET \
  --url https://app.sendmux.ai/api/v1/mailbox/messages \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://app.sendmux.ai/api/v1/mailbox/messages"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.sendmux.ai/api/v1/mailbox/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.sendmux.ai/api/v1/mailbox/messages"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "ok": true,
  "data": [
    {
      "bcc": [
        {
          "email": "agent@example.com",
          "name": "Support"
        }
      ],
      "cc": [
        {
          "email": "agent@example.com",
          "name": "Support"
        }
      ],
      "flags": {
        "answered": true,
        "draft": true,
        "flagged": true,
        "seen": true
      },
      "folder_ids": [
        "<string>"
      ],
      "from": {
        "email": "agent@example.com",
        "name": "Support"
      },
      "has_attachments": true,
      "id": "<string>",
      "keywords": [
        "$seen",
        "$flagged",
        "agent_triaged"
      ],
      "preview": "<string>",
      "received_at": "<string>",
      "sent_at": "<string>",
      "size_bytes": 123,
      "subject": "<string>",
      "thread_id": "<string>",
      "to": [
        {
          "email": "agent@example.com",
          "name": "Support"
        }
      ],
      "attachments": [
        {
          "content_id": "<string>",
          "content_type": "application/pdf",
          "disposition": "attachment",
          "filename": "invoice.pdf",
          "id": "<string>",
          "size_bytes": 12345,
          "download_url": "https://app.sendmux.ai/api/v1/mailbox/messages/msg_123/attachment-downloads/attref_abc123?download_token=..."
        }
      ]
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "<string>"
  }
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "<string>",
    "retryable": false,
    "doc_url": "<string>",
    "errors": [
      {
        "code": "invalid_string",
        "field": "recipient.email",
        "message": "<string>"
      }
    ],
    "param": "<string>"
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "ok": false
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "<string>",
    "retryable": false,
    "doc_url": "<string>",
    "errors": [
      {
        "code": "invalid_string",
        "field": "recipient.email",
        "message": "<string>"
      }
    ],
    "param": "<string>"
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "ok": false
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "<string>",
    "retryable": false,
    "doc_url": "<string>",
    "errors": [
      {
        "code": "invalid_string",
        "field": "recipient.email",
        "message": "<string>"
      }
    ],
    "param": "<string>"
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "ok": false
}

GET

mailbox

messages

List mailbox messages

curl --request GET \
  --url https://app.sendmux.ai/api/v1/mailbox/messages \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://app.sendmux.ai/api/v1/mailbox/messages"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.sendmux.ai/api/v1/mailbox/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.sendmux.ai/api/v1/mailbox/messages"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "ok": true,
  "data": [
    {
      "bcc": [
        {
          "email": "agent@example.com",
          "name": "Support"
        }
      ],
      "cc": [
        {
          "email": "agent@example.com",
          "name": "Support"
        }
      ],
      "flags": {
        "answered": true,
        "draft": true,
        "flagged": true,
        "seen": true
      },
      "folder_ids": [
        "<string>"
      ],
      "from": {
        "email": "agent@example.com",
        "name": "Support"
      },
      "has_attachments": true,
      "id": "<string>",
      "keywords": [
        "$seen",
        "$flagged",
        "agent_triaged"
      ],
      "preview": "<string>",
      "received_at": "<string>",
      "sent_at": "<string>",
      "size_bytes": 123,
      "subject": "<string>",
      "thread_id": "<string>",
      "to": [
        {
          "email": "agent@example.com",
          "name": "Support"
        }
      ],
      "attachments": [
        {
          "content_id": "<string>",
          "content_type": "application/pdf",
          "disposition": "attachment",
          "filename": "invoice.pdf",
          "id": "<string>",
          "size_bytes": 12345,
          "download_url": "https://app.sendmux.ai/api/v1/mailbox/messages/msg_123/attachment-downloads/attref_abc123?download_token=..."
        }
      ]
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "<string>"
  }
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "<string>",
    "retryable": false,
    "doc_url": "<string>",
    "errors": [
      {
        "code": "invalid_string",
        "field": "recipient.email",
        "message": "<string>"
      }
    ],
    "param": "<string>"
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "ok": false
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "<string>",
    "retryable": false,
    "doc_url": "<string>",
    "errors": [
      {
        "code": "invalid_string",
        "field": "recipient.email",
        "message": "<string>"
      }
    ],
    "param": "<string>"
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "ok": false
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "<string>",
    "retryable": false,
    "doc_url": "<string>",
    "errors": [
      {
        "code": "invalid_string",
        "field": "recipient.email",
        "message": "<string>"
      }
    ],
    "param": "<string>"
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "ok": false
}

Authorizations

Authorization

string

header

required

Sendmux API key. Use a root API key for Management API routes, or a mailbox credential for Mailbox API routes. Obtain keys from the dashboard under API Keys.

Query Parameters

cursor

string

Pagination cursor — the next_cursor from the previous response.

limit

integer

Maximum results (default 50, max 100).

Required range: 1 <= x <= 100

folder_id

string

Filter to messages in this folder ID.

thread_id

string

Filter to messages in this thread ID.

string

Full-text search query across message fields.

from

string

Filter by sender email address or display name.

string

Filter by To recipient email address or display name.

string

Filter by CC recipient email address or display name.

bcc

string

Filter by BCC recipient email address or display name.

subject

string

Filter by subject text.

body

string

Filter by message body text.

header_name

string

Header name to match with header_value.

header_value

string

Header value to match with header_name.

min_size_bytes

integer

Minimum message size in bytes.

Required range: x >= 0

max_size_bytes

integer

Maximum message size in bytes.

Required range: x >= 0

keyword

string

Require this message keyword, such as $seen.

not_keyword

string

Exclude messages with this keyword.

after

string

Filter to messages after this ISO 8601 timestamp.

before

string

Filter to messages before this ISO 8601 timestamp.

has_attachment

boolean

When true, only return messages with attachments.

is_unread

boolean

When true, only return unread messages.

sort_by

enum<string>

Message field to sort by.

Available options:

received_at,

sent_at,

subject,

from,

to,

size_bytes

sort_direction

enum<string>

Sort direction.

Available options:

asc,

desc

mailbox_id

string

Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.

Response

Message list

meta

object

required

Hide child attributes

meta.request_id

string

required

Example:

"req_clxxxxxxxxxxxxxxxxxxxxxxxxx"

enum<boolean>

required

Available options:

true

data

object[]

required

Hide child attributes

data.bcc

object[]

required

Hide child attributes

data.bcc.email

string<email>

required

Example:

"agent@example.com"

data.bcc.name

string | null

required

Example:

"Support"

data.cc

object[]

required

Hide child attributes

data.cc.email

string<email>

required

Example:

"agent@example.com"

data.cc.name

string | null

required

Example:

"Support"

data.flags

object

required

Hide child attributes

data.flags.answered

boolean

required

data.flags.draft

boolean

required

data.flags.flagged

boolean

required

data.flags.seen

boolean

required

data.folder_ids

string[]

required

data.from

object

required

Hide child attributes

data.from.email

string<email>

required

Example:

"agent@example.com"

data.from.name

string | null

required

Example:

"Support"

data.has_attachments

boolean

required

data.id

string

required

Message ID

data.keywords

string[]

required

Active message keywords, including system flags and custom labels.

Example:

["$seen", "$flagged", "agent_triaged"]

data.preview

string | null

required

data.received_at

string | null

required

data.sent_at

string | null

required

data.size_bytes

integer | null

required

data.subject

string | null

required

data.thread_id

string | null

required

data.to

object[]

required

Hide child attributes

data.to.email

string<email>

required

Example:

"agent@example.com"

data.to.name

string | null

required

Example:

"Support"

data.attachments

object[]

Attachment metadata for this message. Each item includes a short-lived download_url; if it expires, fetch message metadata again.

Hide child attributes

data.attachments.content_id

string | null

required

Content ID for inline attachments, when present.

data.attachments.content_type

string

required

Example:

"application/pdf"

data.attachments.disposition

string | null

required

Example:

"attachment"

data.attachments.filename

string | null

required

Example:

"invoice.pdf"

data.attachments.id

string

required

Attachment blob ID.

data.attachments.size_bytes

integer | null

required

Example:

12345

data.attachments.download_url

string

Short-lived URL for this exact attachment. Fetch it promptly; if it expires, call the message or attachment metadata endpoint again to receive a fresh URL.

Example:

"https://app.sendmux.ai/api/v1/mailbox/messages/msg_123/attachment-downloads/attref_abc123?download_token=..."

pagination

object

required

Hide child attributes

pagination.has_more

boolean

required

pagination.next_cursor

string

List mailbox sender identities

Batch get mailbox messages

Overview

Mailbox

Messages

Threads

Folders

Submissions

Usage

Sync

List mailbox messages

Authorizations

Query Parameters

Response