import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.agents.update(
  "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  {
    status: "paused",
  },
);
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.update_agent(
    "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
    status="paused",
)
print(result)

curl -X PATCH 'https://api.mails.ai/v1/agents/agt_01JZX8K3M9Q4P7VN2YB6RTDC0E' \
  -H "Authorization: Bearer $MAILS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "status": "paused" }'

mails agents update hello --status paused
mails agents update hello --daily-send-limit null

{
  "name": "mails_agents_update",
  "arguments": {
    "agent": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
    "status": "paused"
  }
}

{
  "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"
}

200  The updated agent.
400  Invalid request — malformed JSON or a field failed
     validation. Also feature_not_enabled when this
     server has a feature switched off (custom domains
     before they are available).
401  Missing or invalid API key.
402  Payment required: a plan limit
     (plan_limit_exceeded) or a feature the current plan
     does not include (feature_not_enabled). The error
     object carries upgrade_url, the dashboard page
     where the plan can be changed.
403  The API key lacks the required scope
     (insufficient_scope), or the token belongs to an
     app connected by sign-in and this operation is
     closed to connected apps
     (connected_app_not_allowed).
404  Resource not found in this workspace, or the agent
     a send names is archived (agent_archived).
409  Conflict — duplicate resource, an in-progress
     idempotent request, a draft or scheduled message
     that started sending while it was being changed, or
     a thread deleted for good while one of its messages
     is being sent (duplicate_resource); or an agent
     name more than one agent has (agent_name_conflict:
     use the agent's id); or a status change on an
     archived agent, since archiving cannot be undone
     (agent_archived).
500  Internal server error.

Update an agent

Changes an agent's status, recipient lists, send limits, or whether its new mail is read for intent.

PATCH/v1/agents/{id}scope · manage

import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.agents.update(
  "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  {
    status: "paused",
  },
);
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.update_agent(
    "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
    status="paused",
)
print(result)

curl -X PATCH 'https://api.mails.ai/v1/agents/agt_01JZX8K3M9Q4P7VN2YB6RTDC0E' \
  -H "Authorization: Bearer $MAILS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "status": "paused" }'

mails agents update hello --status paused
mails agents update hello --daily-send-limit null

{
  "name": "mails_agents_update",
  "arguments": {
    "agent": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
    "status": "paused"
  }
}

{
  "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"
}

200  The updated agent.
400  Invalid request — malformed JSON or a field failed
     validation. Also feature_not_enabled when this
     server has a feature switched off (custom domains
     before they are available).
401  Missing or invalid API key.
402  Payment required: a plan limit
     (plan_limit_exceeded) or a feature the current plan
     does not include (feature_not_enabled). The error
     object carries upgrade_url, the dashboard page
     where the plan can be changed.
403  The API key lacks the required scope
     (insufficient_scope), or the token belongs to an
     app connected by sign-in and this operation is
     closed to connected apps
     (connected_app_not_allowed).
404  Resource not found in this workspace, or the agent
     a send names is archived (agent_archived).
409  Conflict — duplicate resource, an in-progress
     idempotent request, a draft or scheduled message
     that started sending while it was being changed, or
     a thread deleted for good while one of its messages
     is being sent (duplicate_resource); or an agent
     name more than one agent has (agent_name_conflict:
     use the agent's id); or a status change on an
     archived agent, since archiving cannot be undone
     (agent_archived).
500  Internal server error.

Path Parameters

idstringrequired

Agent id or name.

Body Parameters

statusstring

paused makes the agent's send requests fail with 422 agent_paused; active resumes it.

One of: active, paused

A pause set by the bounce, complaint or abuse checks cannot be lifted this way (403 agent_suspended).

allowlist_domainsstring[]

When set, this agent sends only to these domains and their subdomains (acme.com covers mail.acme.com). A recipient in to, cc or bcc outside the list refuses the whole send with 422 recipient_not_allowed, in test mode too. A leading @ is ignored. The test address reply@test.mails.ai is always allowed.

blocklist_domainsstring[]

This agent never sends to these domains or their subdomains. A recipient in to, cc or bcc on the list refuses the whole send with 422 recipient_not_allowed, in test mode too. The test address reply@test.mails.ai is never blocked.

daily_send_limitinteger | null

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 is refused with 429 daily_limit_exceeded, whose resets_at says when the send fits again (with a Retry-After header only when that is a minute or less away). Test-mode sends are neither counted nor refused. null removes it, leaving only your plan's cap.

hourly_send_limitinteger | null

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 is refused with 429 hourly_limit_exceeded, whose resets_at says when the send fits again (with a Retry-After header only when that is a minute or less away). Test-mode sends are neither counted nor refused. null removes it, leaving only your plan's cap.

classify_inboundboolean

Turns intent classification of new mail on or off (never replies in a thread). Turning it on needs a paid plan (402 feature_not_enabled); left out, it stays as it is.

addressstring

The agent's own address, which never changes: any other address answers 400. Accepted so a body that names it alongside forwarding works.

forwardingboolean

Forwarding mode, for an address on your own domain: the mail service hosting it forwards its mail to the agent's forwarding_address, so no MX record changes. POST /v1/agents/{id}/forwarding/verify then sends a test through the forward. Turning it on or off starts forwarding_status again from not_verified.

A pause by our abuse-prevention system or for the agent's own bounce or complaint rate cannot be lifted here (403 agent_suspended), and pausing such an agent again keeps that reason. Archiving cannot be undone, so an archived agent's status cannot change (409 agent_archived), and a status change that meets an agent archived or paused meanwhile answers 409 too. A key tied to the agent, or an app connected by sign-in, cannot change allowlist_domains, blocklist_domains, daily_send_limit or hourly_send_limit (403): they hold the agent to what the workspace allows, so only a key that is not tied to an agent changes them. A test key cannot change an agent that has a live key tied to it, live mail (sent, scheduled or received) or a draft a live key made (403 live_mode_required).

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?