Agents

Test an agent's forwarding

Requires scope: manage. For an agent in forwarding mode: sends one test email from mails.ai to the agent's own address. When your mail service forwards it to the agent's forwarding_address, it is dropped there (the agent never sees it) and forwarding_status becomes verified; if it has not arrived 15 minutes after it was sent, failing. Answers the agent at once: poll GET /v1/agents/{id}. While a test is on its way, calling again sends nothing more; at most 10 tests an hour per agent. A test key gets 403 live_mode_required, since this sends a real email. A test the email service does not take changes nothing and answers as a send does: 503 upstream_unavailable with Retry-After when it is not taking more mail, 422 recipient_suppressed when it refused the agent's address, else 502 upstream_error.

post/v1/agents/{id}/forwarding/verify

Request

  • Base URL: https://api.mails.ai
  • URL: https://api.mails.ai/v1/agents/{id}/forwarding/verify
  • Auth: HTTP bearer

Path parameters

idstring required

Agent id or name.

Response

The agent, with forwarding_test_sent_at set.

idstring required

Agent id (agt_…).

namestring required

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 email required

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

domainstring required

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 email required

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.

workspace_idstring required

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

status'active' | 'paused' | 'archived' required

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.

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 email nullable

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_status'not_verified' | 'verified' | 'failing' | 'null' nullable

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.

forwarding_test_sent_atstring date-time nullable

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

forwarding_verified_atstring date-time nullable

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

created_atstring date-time

When the agent was created.

updated_atstring date-time

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.