Transactional

Inbox Management

List, search, read, label, and archive messages in agent mailboxes via API.

List Messages

Retrieve messages from a mailbox with filtering and pagination.

const messages = await tx.agentEmail.inbox.list({
  mailbox: mailbox.id,
  limit: 25,
  offset: 0,
  sort: 'received_at:desc',
});
 
// Response
{
  data: [
    {
      id: 'msg_abc123',
      from: 'user@example.com',
      to: ['agent@agentmail.usetransactional.com'],
      subject: 'Re: Research Request',
      textPreview: 'Thanks for the update. Can you also...',
      read: false,
      labels: ['inbox'],
      threadId: 'thd_xyz789',
      receivedAt: '2025-01-10T14:30:00Z',
    },
    // ...
  ],
  meta: { total: 142, limit: 25, offset: 0 },
}

Filter Messages

Filter by read status, labels, date range, and sender.

// Unread messages only
const unread = await tx.agentEmail.inbox.list({
  mailbox: mailbox.id,
  unread: true,
});
 
// Messages with a specific label
const important = await tx.agentEmail.inbox.list({
  mailbox: mailbox.id,
  label: 'important',
});
 
// Messages from a specific sender
const fromUser = await tx.agentEmail.inbox.list({
  mailbox: mailbox.id,
  from: 'user@example.com',
});
 
// Messages within a date range
const recent = await tx.agentEmail.inbox.list({
  mailbox: mailbox.id,
  after: '2025-01-01T00:00:00Z',
  before: '2025-01-31T23:59:59Z',
});

Search Messages

Full-text search across subject and body content.

const results = await tx.agentEmail.inbox.search({
  mailbox: mailbox.id,
  query: 'quarterly report',
  limit: 10,
});

Read a Message

Retrieve the full content of a single message.

const message = await tx.agentEmail.inbox.get(messageId);
 
console.log(message.from);        // 'user@example.com'
console.log(message.subject);     // 'Re: Research Request'
console.log(message.htmlBody);    // Full HTML content
console.log(message.textBody);    // Plain text content
console.log(message.attachments); // Array of attachments
console.log(message.headers);     // All email headers

Reading a message automatically marks it as read. To prevent this:

const message = await tx.agentEmail.inbox.get(messageId, {
  markRead: false,
});

Mark Read / Unread

// Mark a single message as read
await tx.agentEmail.inbox.markRead(messageId);
 
// Mark as unread
await tx.agentEmail.inbox.markUnread(messageId);
 
// Bulk mark as read
await tx.agentEmail.inbox.markRead([msgId1, msgId2, msgId3]);

Labels

Organize messages with custom labels.

// Add a label
await tx.agentEmail.inbox.addLabel(messageId, 'important');
 
// Remove a label
await tx.agentEmail.inbox.removeLabel(messageId, 'important');
 
// Add multiple labels
await tx.agentEmail.inbox.addLabels(messageId, ['urgent', 'follow-up']);
 
// List all labels for a mailbox
const labels = await tx.agentEmail.labels.list({
  mailbox: mailbox.id,
});
// → ['inbox', 'important', 'urgent', 'follow-up', 'archived']

Create Custom Labels

await tx.agentEmail.labels.create({
  mailbox: mailbox.id,
  name: 'needs-review',
  color: '#3B82F6',
});

Archive

Move messages out of the inbox without deleting them.

// Archive a message
await tx.agentEmail.inbox.archive(messageId);
 
// Unarchive
await tx.agentEmail.inbox.unarchive(messageId);
 
// Bulk archive
await tx.agentEmail.inbox.archive([msgId1, msgId2]);
 
// List archived messages
const archived = await tx.agentEmail.inbox.list({
  mailbox: mailbox.id,
  label: 'archived',
});

Delete

Permanently delete messages.

// Delete a single message
await tx.agentEmail.inbox.delete(messageId);
 
// Bulk delete
await tx.agentEmail.inbox.delete([msgId1, msgId2]);

Deleted messages cannot be recovered.

Next Steps