Mails.ai — Agent Email

Stage a draft. With send_at it is scheduled.

Registers a custom sending domain (paid plans) and returns the DNS records to create at the domain's registrar. Agents whose address is on a verified custom domain send under that address.

Removes a custom domain. Agents whose address is on it cannot send (422 `domain_not_verified`) until the domain is added and verified again. Returns its id.

Returns one custom domain with its overall and per-record verification status.

Lists the workspace's custom sending domains with their verification status and DNS records.

Checks every DNS record of a custom domain now and returns the domain with its per-record and overall status. DNS changes usually take minutes to be seen. Each call that does not pass counts: 20 in a row mark the domain `failed`, which is still re-checked automatically and verifies once its records resolve. The count starts over on success or after a day without a call.

Deletes a draft, or a scheduled draft before it is sent. Returns its id and when it was deleted.

Returns one draft by its id: recipients, subject, body, `send_at` and status.

Lists drafts and scheduled drafts, newest first, filtered by agent or status; `next_cursor` fetches the next page.

Edits a draft's recipients, subject, body or `send_at`. A future `send_at` schedules the draft to be sent then, and clearing it makes it a plain draft again. A draft that failed only because its agent was paused can be changed and scheduled again once the agent is resumed. Returns the draft.

Asks for an independent second review of content the cold-email firewall refused (`cold_email_prohibited`), given the same agent, subject and body the refused send used. Returns `outcome`: `overturned` (that exact content may be sent for the next 24 hours), `upheld`, `not_appealable` (a fixed policy block, with no review) or `not_blocked`. Within 24 hours the same content gets back the outcome it was given, never a new review. At most 10 appeals per workspace per 24 hours.

Cancels an email that is still scheduled, so it is never sent. Cancelling cannot be undone. An email that has started going out cannot be canceled (409). Returns its id, status `canceled` and when it was canceled.

Returns one sent or scheduled email by its `msg_` id: recipients, subject, body, status, delivery times, tags and metadata.

Lists emails the workspace's agents sent or scheduled, newest first, with recipients, subject, status and timestamps. Filters by agent, thread or text in the subject, body or recipient addresses; `next_cursor` fetches the next page.

Returns a sent email (`msg_` id) as an RFC 822 message rebuilt from what is stored: its headers and its HTML or text body, without attachments. For a received email (`rcv_` id) only the header block comes back (the original headers when the raw email was kept, else ones rebuilt from what is stored): its body reaches a model only as text, through mails_get_received. Text past 100,000 characters is cut short.

Moves a scheduled email to a new send time. Only an email whose status is `scheduled` can move, or one that failed only because its agent was paused when it came due, once the agent is resumed. It needs the `send` scope as well as `manage`, and a live key for live mail. Returns its id, the new `scheduled_at` and its status.

Sends up to 100 emails in one call, each with its own agent, recipients and content. A message that fails is reported in its place in `data` and does not stop the others. Sent mail cannot be recalled.

Lists events newest first (message.sent, message.delivered, message.bounced, reply.received, message.received, thread.updated and the rest), of one type, for one agent or since a time if asked. Inbound events carry the injection score; `message.received` (new mail) can also carry an intent read from the message when the agent's classify_inbound is on, and on `reply.received` the intent is always `general_reply`. `next_cursor` fetches the next page.

Sends a stored event again to every webhook endpoint subscribed to its type. Returns the event id and the endpoints it was queued for.

Forward a message to new recipients.

Get one event by its id (evt_…), whatever its type: received mail, a send, a draft or a suppression. For received mail it also carries injection_categories, which the list leaves out.

Get one received message: its text, including the extracted reply text. Never its HTML.

Get an agent's sending-reputation health (0-1) + its 30-day bounce/complaint/reply counts. The firewall auto-suspends an agent that crosses a 0.3% complaint rate. A key tied to one agent reads only that agent's reputation.

Get a full thread with all messages in chronological order.

Get the current billing period usage.

Returns whether the mails.ai API is up (`healthy` or `degraded`) and its clock. Needs no credential.

Creates a label with a name (unique in the workspace, ignoring case) and a colour from a fixed palette of 12. Returns the label.

Deletes a label and takes it off every thread that carries it. Returns its id.

Returns one label by its `lbl_` id.

Lists the workspace's labels (at most 200) by name, each with its id and colour.

Renames a label or changes its colour. A new name applies to every thread that carries the label. Returns the label.

List the agents in the workspace. Returns SENDABLE agents by default (status=live); archived agents cannot send, so they are excluded unless asked for: status="all" includes them.

List recent cold/first-contact inbound (message.received) for an agent — senders that are NOT replying to one of your sends — together with mail that failed authentication (message.received.unauthenticated: its From domain's DMARC policy is quarantine or reject, and no DKIM signature aligned with that domain verifies), newest first. Each event carries `unauthenticated`, true for the failed ones.

List recently received messages. Text only: never the sender's HTML.

List recent reply events (reply.received) for an agent. A reply that failed authentication is not a reply event: mails_list_messages lists it, as message.received.unauthenticated.

List threads (conversations) for the workspace or a specific agent.

Lists the workspace's audit log of changes, newest first, filtered by category or action if asked.

Who am I — returns the authenticated workspace, agent, tier, and API-key scopes, with this server's version and how many tools this credential can use.

Returns counts of sent, delivered, bounced, complained, received and reply messages per day or per hour (UTC), for the workspace or one agent. Without a range: the last 30 days by day, or the last 48 hours by hour.

Reply in-thread to a message. A received message (rcv_…) is answered to its sender, or to the Reply-To address it named; one of your own sent messages (msg_…) is followed up to its recipients. In-Reply-To, References and the Re: subject are set server-side, and the original is not quoted.

Full-text search over received and sent mail (subject, body and addresses), newest first; every word must match. Narrows by agent, sender, recipient, date range, attachment, folder, label or direction. Each hit says whether it was `received` or `sent` and carries a snippet around the match.

Send an email. `agent` is OPTIONAL: without it the workspace's single agent is used, or one is created (named from `from`) when this connection may create agents (Full access, or a key with `manage`), so a first send needs no setup; with several agents, `agent` says which one sends. The reputation firewall runs on every send: an agent auto-suspended for crossing a 0.3% complaint rate is blocked (422 agent_paused), a send with a suppressed address in to, cc or bcc is refused whole (422 recipient_suppressed), and the response returns the classifier_score, which shows how the send was graded.

Send a previously-created draft.

Lists the workspace's allowlist: addresses mail may go to despite a suppression, each with its attestation. With `view: suppressed` it lists instead which of the workspace's recent recipients are suppressed, and why (up to 500).

Removes an allowlist entry by its id, so the suppression applies to that address again. Returns its id and when it was revoked.

SANDBOX (test key only): simulate an email arriving to one of your agents, to exercise the whole two-way loop — receive → prompt-injection scan → reply — with NO live mail server and no waiting. This runs the REAL reputation firewall. The VERDICT is the top-level `quarantined` (boolean — true means we judged it an attack); the evidence sits in the `classification` block: injection_score (0-1), injection_categories, intent, entities, sender_reputation. A body_text that hides an instruction aimed at the agent, such as a request to forward its contacts to an outside address, is flagged by the inj…

Moves a thread to trash, where mails_threads_update can move it back and where it is emptied after 30 days. With `permanent: true` the thread is deleted for good, from any folder: its messages, raw email and attachments are removed and cannot be recovered.

Marks a thread read or unread, moves it to inbox, archive, spam or trash, sets its status (`open`, `closed`, `archived`) or replaces its labels. Archiving files the thread in archive, and moving an archived thread anywhere else reopens it. Returns the thread.

Returns the newest received email that matches, waiting up to `timeout` seconds (0 to 50, default 30) for one to arrive: after asking a service for a sign-up code, a magic link or a password reset, name the sender with `from` (an address, or a domain and its subdomains) and `has: code` or `has: link`. The email carries `codes` (each a `value`) and `links` (each a `url` and a `kind`: verify, sign_in, reset_password, unsubscribe, other). Mail judged forged and quarantined mail never match. `message` is null and `timed_out` true when none arrived in time.

Registers an HTTPS endpoint that receives the workspace's events: every event, or the listed types. Returns the endpoint with its `signing_secret`, which is shown only this once.

Deletes a webhook endpoint and its delivery history. Returns its id and when it was deleted.

Returns one webhook endpoint by its id.

Lists the workspace's webhook endpoints with their URL, event types, description and whether each is active. Signing secrets are never listed.

Lists a webhook endpoint's delivery attempts, newest first, each with its event, attempt number, status, HTTP status, the start of the endpoint's answer (or why it could not be reached), and when it was made, delivered and next retried.

Sends the event behind a past delivery attempt again. Returns the delivery and event ids and the endpoints it was queued for.

Issues a new signing secret for a webhook endpoint, returned only this once. For the next 24 hours every delivery carries signatures from both the new and the previous secret, so a receiver can switch over without a failed delivery.

Sends a synthetic `webhook.test` event to a webhook endpoint, signed like a real delivery, and returns whether it answered with a 2xx (`ok`), its HTTP status (null when it could not be reached) and the start of its answer. The attempt is listed among the endpoint's deliveries.

Changes a webhook endpoint's URL, event types, description or whether it is active. Returns the endpoint.