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

const client = createClient(); // reads MAILS_API_KEY

const result = await client.agents.create("support");
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.create_agent("support")
print(result)

curl -X POST 'https://api.mails.ai/v1/agents' \
  -H "Authorization: Bearer $MAILS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "support",
  "daily_send_limit": 5000,
  "classify_inbound": true
}'

mails agents create support
mails agents create billing --domain mail.acme.com \
  --daily-send-limit 5000

{
  "name": "mails_create_agent",
  "arguments": {
    "name": "support",
    "classify_inbound": true,
    "daily_send_limit": 5000
  }
}

{
  "id": "agt_01JZ9F8H7KQ2M3N4P5R6S7T8W2",
  "name": "support",
  "email": "support@acme.mails.ai",
  "domain": "acme.mails.ai",
  "receiving_address": "support.acme@in.mails.ai",
  "workspace_id": "wsk_01JZ8A1B2C3D4E5F6G7H8J9K0M",
  "status": "active",
  "daily_send_limit": 5000,
  "classify_inbound": true,
  "forwarding": false,
  "forwarding_address": null,
  "forwarding_status": null,
  "forwarding_test_sent_at": null,
  "forwarding_verified_at": null,
  "created_at": "2026-06-01T09:12:44.000Z",
  "updated_at": "2026-06-01T09:12:44.000Z"
}

201  The created 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).
422  Unprocessable — agent paused, recipient suppressed,
     a recipient at test.mails.ai other than
     reply@test.mails.ai (unknown_test_address), or
     abuse guard.
500  Internal server error.

Create an agent

Creates an agent (a send/receive identity) at name@<workspace>.mails.ai, or at an address on a domain your workspace has verified for sending.

POST/v1/agentsscope · manage

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

const client = createClient(); // reads MAILS_API_KEY

const result = await client.agents.create("support");
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.create_agent("support")
print(result)

curl -X POST 'https://api.mails.ai/v1/agents' \
  -H "Authorization: Bearer $MAILS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "support",
  "daily_send_limit": 5000,
  "classify_inbound": true
}'

mails agents create support
mails agents create billing --domain mail.acme.com \
  --daily-send-limit 5000

{
  "name": "mails_create_agent",
  "arguments": {
    "name": "support",
    "classify_inbound": true,
    "daily_send_limit": 5000
  }
}

{
  "id": "agt_01JZ9F8H7KQ2M3N4P5R6S7T8W2",
  "name": "support",
  "email": "support@acme.mails.ai",
  "domain": "acme.mails.ai",
  "receiving_address": "support.acme@in.mails.ai",
  "workspace_id": "wsk_01JZ8A1B2C3D4E5F6G7H8J9K0M",
  "status": "active",
  "daily_send_limit": 5000,
  "classify_inbound": true,
  "forwarding": false,
  "forwarding_address": null,
  "forwarding_status": null,
  "forwarding_test_sent_at": null,
  "forwarding_verified_at": null,
  "created_at": "2026-06-01T09:12:44.000Z",
  "updated_at": "2026-06-01T09:12:44.000Z"
}

201  The created 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).
422  Unprocessable — agent paused, recipient suppressed,
     a recipient at test.mails.ai other than
     reply@test.mails.ai (unknown_test_address), or
     abuse guard.
500  Internal server error.

Body Parameters

namestring

The agent's name and the part of its address before the @: 1 to 32 lowercase letters, digits, ., _ or -. Required unless address is given, which names the agent after its local part. A name already used on that domain, by an archived agent too, is refused with 400 duplicate_resource. On the workspace's own mails.ai subdomain the agent sends and receives as <name>.<slug>, and an address may have at most 64 characters before the @, so a name that makes it longer is refused with 400 invalid_param_value.

domainstring

The domain of the agent's address. Left out, it is your workspace's <slug>.mails.ai, or the domain of address when that is given. Any other value must be a custom domain this workspace has verified (400 domain_not_verified otherwise).

addressstring

The agent's address, on a domain your workspace has verified for sending (support@acme.com). The agent is named after its local part, so name may be left out. Past your plan's agent limit it answers 402 resource_cap_exceeded, as any agent create does.

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.

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

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. Leave it out to use only your plan's cap.

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 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. Leave it out to use only your plan's cap.

classify_inboundboolean

Also read this agent's new mail for intent, entities and urgency (never a reply in a thread). Needs a paid plan (402 feature_not_enabled). Off unless set. Its message.received events then carry an intent, entities and urgency, and on reply.received the intent is always general_reply. The injection scan runs either way.

Add forwarding: true when the mail service that already hosts that address will forward its mail to the agent's forwarding_address (no MX change), then test it with POST /v1/agents/{id}/forwarding/verify. Past your plan's agent limit it answers 402 resource_cap_exceeded, however many requests arrive together, on your own domain as on your mails.ai address (a send whose from names a new address answers plan_limit_exceeded instead). While the workspace has an agent suspended by abuse prevention, archived or not, it answers 422 agent_paused.

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?