List Messages

Authentication

Requires the inbox's API key in the Authorization header.

Path Parameters

idstringpathrequired

Inbox ID (e.g., inb_abc123)

Query Parameters

labelstringquery

Filter by label (e.g., verification, newsletter)

thread_idstringquery

Filter by thread UUID

beforestringquery

ISO 8601 datetime - messages received before this time

afterstringquery

ISO 8601 datetime - messages received after this time

limitintegerquery

Number of messages to return (1-100)

sortstringquery

Sort order: desc (newest first) or asc (oldest first)

Request

curl -X GET "https://api.daimon.email/v1/inboxes/inb_abc123/messages?limit=20&sort=desc" \
  -H "Authorization: Bearer dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o"

const client = new DaimonClient({ apiKey: 'dm_free_...' });

const response = await client.inboxes.messages.list('inb_abc123', {
  limit: 20,
  sort: 'desc',
  label: 'verification'
});

console.log(`Total: ${response.total}`);
console.log(`Has more: ${response.hasMore}`);

response.messages.forEach(msg => {
  console.log(`${msg.subject} - ${msg.preview}`);
  console.log(`Links: ${msg.ctaLinks}`);
});

client = DaimonClient(api_key='dm_free_...')

response = client.inboxes.messages.list('inb_abc123',
    limit=20,
    sort='desc',
    label='verification'
)

print(f"Total: {response.total}")
print(f"Has more: {response.has_more}")

for msg in response.messages:
    print(f"{msg.subject} - {msg.preview}")
    print(f"Links: {msg.cta_links}")

Response

{
  "result": {
    "messages": [
      {
        "id": "msg_xyz789",
        "inbox_id": "inb_abc123",
        "thread_id": "thr_def456",
        "from_address": "support@example.com",
        "to_address": "my-agent@daimon.email",
        "subject": "Verify your account",
        "body_text": "Click here to verify: https://example.com/verify?token=abc123",
        "body_html": "<p>Click here to verify: <a href=\"https://example.com/verify?token=abc123\">Verify</a></p>",
        "reply_body": "Click here to verify: https://example.com/verify?token=abc123",
        "links": [
          "https://example.com/verify?token=abc123"
        ],
        "cta_links": [
          "https://example.com/verify?token=abc123"
        ],
        "preview": "Click here to verify: https://example.com/verify?token=abc123",
        "labels": ["verification"],
        "read": false,
        "received_at": "2024-03-11T14:23:45Z",
        "created_at": "2024-03-11T14:23:46Z"
      }
    ],
    "total": 42,
    "has_more": true
  },
  "next_steps": [
    "Call GET /v1/inboxes/{id}/messages/{msgId} for full message details",
    "Use thread_id to retrieve all messages in a conversation",
    "Filter by label='verification' to find confirmation emails"
  ]
}

Response Fields

result.messagesarray

Array of message objects

result.messages[].idstring

Message ID (e.g., msg_xyz789)

result.messages[].inbox_idstring

Parent inbox ID

result.messages[].thread_idstring

Thread ID - groups related messages

result.messages[].from_addressstring

Sender email address

result.messages[].to_addressstring

Recipient email address (your inbox)

result.messages[].subjectstring

Email subject line

result.messages[].body_textstring

Plain text body

result.messages[].body_htmlstring

HTML body (if available)

result.messages[].reply_bodystring

Extracted reply text without quoted history (via TalonJS)

result.messages[].linksarray

All URLs found in the message

result.messages[].cta_linksarray

Detected call-to-action links (verify, confirm, activate, etc.)

result.messages[].previewstring

First ~150 characters of the message

result.messages[].labelsarray

Auto-detected labels (e.g., verification, newsletter)

result.messages[].readboolean

Whether the message has been marked as read

result.messages[].received_atstring

ISO 8601 timestamp of when the message was received

result.messages[].created_atstring

ISO 8601 timestamp of when the message was stored

result.totalinteger

Total number of messages matching the filter

result.has_moreboolean

Whether there are more messages beyond the current page

next_stepsarray

Agent guidance for next actions

Use Cases

Poll for verification emails

// Agent polls for verification emails every 5 seconds
const messages = await client.inboxes.messages.list('inb_abc123', {
  label: 'verification',
  limit: 1,
  sort: 'desc'
});

if (messages.messages.length > 0) {
  const verifyUrl = messages.messages[0].cta_links[0];
  console.log(`Verification link: ${verifyUrl}`);
}

Check for new messages since last check

const lastCheck = '2024-03-11T14:00:00Z';

const messages = await client.inboxes.messages.list('inb_abc123', {
  after: lastCheck,
  sort: 'asc'
});

console.log(`${messages.messages.length} new messages`);

Find all messages in a thread

const messages = await client.inboxes.messages.list('inb_abc123', {
  thread_id: 'thr_def456',
  sort: 'asc' // Chronological order
});

console.log(`Thread has ${messages.total} messages`);