Retrieve an agent
Requires scope: read. Returns an agent by its id or its 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.
Request
- Base URL: https://api.mails.ai
- URL: https://api.mails.ai/v1/agents/{id}
- Auth: HTTP bearer
Path parameters
Agent id or name.
Response
The agent.
Agent id (agt_…).
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.
The agent's address, <name>@<domain>, unique across mails.ai: the identity it sends as. It receives mail at receiving_address.
The domain part of email: your workspace's <slug>.mails.ai, or a custom domain that was verified when the agent was created.
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. Mail to any plus address of it reaches the agent too: add + and anything before the @ (qa.acme+github@in.mails.ai, qa.acme+run-1842@in.mails.ai), so one agent can give every service or test run its own address. The address used is kept as the message's delivered_to, and the to filter on received mail matches it.
Id of the workspace the agent belongs to (wsk_…).
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.
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.
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.
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.
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.
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.
Whether this agent's new mail is read for intent; a reply in a thread never is. The list leaves it out.
Unread threads in the agent's inbox folder, on the list and on the single-agent GET and PATCH.
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.
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.
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.
When the last forwarding test was sent. Null when none was, or forwarding is off.
When a forwarding test last arrived through the forward. Null when none has, or forwarding is off.
When the agent was created.
When the agent last changed: an update, an archive, or an automatic pause or resume. The list leaves it out.
Changes
No recorded changes to this operation across all 1 revision of this API.