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

const client = createClient(); // reads MAILS_API_KEY

const result = await client.agents.get(
  "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);
{
  "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"
}

Retrieve an agent

Returns an agent by its id or its name.
GET/v1/agents/{id}scope · read
import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.agents.get(
  "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);
{
  "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"
}

Path Parameters

idstringrequired

Agent id or name.

A key tied to one agent gets any other agent as 404 agent_not_found, as if it did not exist, and a name other agents share is not reported to it as a 409.

Response

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.

Was this page helpful?