Skip to main content
Get Started
import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.agents.list({ limit: 10 });
console.log(result);
{
  "data": [
    {
      "id": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "name": "<name>",
      "email": "jordan@example.com",
      "domain": "<domain>",
      "receiving_address": "jordan@example.com",
      "workspace_id": "wsk_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "status": "active",
      "pause_reason": "<pause_reason>",
      "daily_send_limit": 0,
      "hourly_send_limit": 0,
      "allowlist_domains": ["<allowlist_domains>"],
      "blocklist_domains": ["<blocklist_domains>"],
      "classify_inbound": false,
      "unread_count": 0,
      "forwarding": false,
      "forwarding_address": "jordan@example.com",
      "forwarding_status": "not_verified",
      "forwarding_test_sent_at": "2026-10-04T12:00:00.000Z",
      "forwarding_verified_at": "2026-10-04T12:00:00.000Z",
      "created_at": "2026-10-04T12:00:00.000Z",
      "updated_at": "2026-10-04T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": "<next_cursor>"
}

List agents

Lists the workspace's agents, newest first.
GET/v1/agentsscope · read
import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.agents.list({ limit: 10 });
console.log(result);
{
  "data": [
    {
      "id": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "name": "<name>",
      "email": "jordan@example.com",
      "domain": "<domain>",
      "receiving_address": "jordan@example.com",
      "workspace_id": "wsk_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "status": "active",
      "pause_reason": "<pause_reason>",
      "daily_send_limit": 0,
      "hourly_send_limit": 0,
      "allowlist_domains": ["<allowlist_domains>"],
      "blocklist_domains": ["<blocklist_domains>"],
      "classify_inbound": false,
      "unread_count": 0,
      "forwarding": false,
      "forwarding_address": "jordan@example.com",
      "forwarding_status": "not_verified",
      "forwarding_test_sent_at": "2026-10-04T12:00:00.000Z",
      "forwarding_verified_at": "2026-10-04T12:00:00.000Z",
      "created_at": "2026-10-04T12:00:00.000Z",
      "updated_at": "2026-10-04T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": "<next_cursor>"
}

Query Parameters

limitinteger

Page size (1–100).

Default: 25

cursorstring

Opaque cursor from a previous page's next_cursor.

statusstring

Which agents to list. Defaults to live — everything except archived — because an archived agent cannot send, so listing tombstones by default answers a different question than the one you asked. Use all to include them, or filter to one exact status.

One of: live, all, active, paused, archived

Default: "live"

A key tied to one agent lists that agent and no other.

Response

dataobject[]

The items on this page, at most limit of them.

Show propertiesHide properties
idstring

Agent id (agt_…).

namestring

The agent's name, the part of email before the @. The agent routes, and agent on sends and drafts, take it in place of the id; agents on different domains can share a name, so the id is the safer reference.

emailstring

The agent's address, <name>@<domain>, unique across mails.ai: the identity it sends as. It receives mail at receiving_address.

domainstring

The domain part of email: your workspace's <slug>.mails.ai, or a custom domain that was verified when the agent was created.

receiving_addressstring

Where this agent receives mail. Every send's Reply-To is this address unless the send sets reply_to, so replies reach the agent. <name>.<slug>@in.mails.ai for an agent on your mails.ai address (<name>@in.mails.ai when the name is the slug); for an agent on your own domain, the name and the whole domain with its dots written as underscores, such as billing.example_com@in.mails.ai.

workspace_idstring

Id of the workspace the agent belongs to (wsk_…).

statusstring

active; paused, when its send requests get 422 agent_paused and pause_reason says why; or archived after a DELETE, when it cannot send and the default list leaves it out.

One of: active, paused, archived

pause_reasonstring

Why the agent is paused or archived: manual (paused with PATCH), archived_via_api (archived with DELETE), or a reason the automatic bounce, complaint and abuse checks set, such as bounce_rate=0.0612. Absent when there is none. The list leaves it out.

daily_send_limitinteger

This agent's own cap on recipients in any 24 hours, on top of your plan's cap: each live send counts once per to, cc and bcc address. Past it, a send gets 429 daily_limit_exceeded. Absent when unset. The list leaves it out.

hourly_send_limitinteger

This agent's own cap on recipients in any hour, on top of your plan's cap: each live send counts once per to, cc and bcc address. Past it, a send gets 429 hourly_limit_exceeded. Absent when unset. The list leaves it out.

allowlist_domainsstring[]

When present, this agent sends only to these domains and their subdomains; any other recipient in to, cc or bcc gets 422 recipient_not_allowed. The test address reply@test.mails.ai is always allowed. The list leaves it out.

blocklist_domainsstring[]

Domains (and their subdomains) this agent never sends to; a recipient on the list gets 422 recipient_not_allowed. The test address reply@test.mails.ai is never blocked. The list leaves it out.

classify_inboundboolean

Whether this agent's new mail is read for intent; a reply in a thread never is. The list leaves it out.

unread_countinteger

Unread threads in the agent's inbox folder, on the list and on the single-agent GET and PATCH.

forwardingboolean

Forwarding mode: the agent's address is on your own domain, and the mail service that already hosts it forwards its mail to forwarding_address, so no MX record changes.

forwarding_addressstring | null

Where to forward the agent's mail: its receiving_address. Mail that arrives here is stored, threaded and sent to your webhooks like any received mail, with the agent's own address as the recipient. Null when forwarding is off.

forwarding_statusstring | null

verified once a test from POST /v1/agents/{id}/forwarding/verify arrived through the forward; failing when the last test had not arrived 15 minutes after it was sent; not_verified before that. Null when forwarding is off.

One of: not_verified, verified, failing

forwarding_test_sent_atstring | null

When the last forwarding test was sent. Null when none was, or forwarding is off.

forwarding_verified_atstring | null

When a forwarding test last arrived through the forward. Null when none has, or forwarding is off.

created_atstring

When the agent was created.

updated_atstring

When the agent last changed: an update, an archive, or an automatic pause or resume. The list leaves it out.

has_moreboolean

True when more items follow this page: pass next_cursor as cursor to get them.

next_cursorstring

Pass as cursor to fetch the next page. Absent on the last page.

Was this page helpful?