Skip to content
Browse the docs

Integrating · Published 2026-09-28 · Updated 2026-10-21 · AgentiSend

Receiving and replying

Read received mail and thread your replies. A reply to mail that arrived somewhere else threads too, with headers copied from it.

Receiving is open: turn it on for a verified domain, publish the MX record its page shows, and mail to that domain arrives on your account.

The receiving routes, threads, replies and attachments below are the calls. Mail sent to a verified domain with receiving turned on is stored on your account, and each message fires an email.received webhook with the sender, recipients, subject, Message-ID and attachment names. The body, headers and attachment bytes are read through the routes below. A reply to mail received somewhere else still threads, with headers copied from it.

Who may write to this domain

A block rule refuses a sender when either the envelope or the From header matches it, and an allow list stores the message when either address matches an allow rule.

inbound_policy is open or allowlist. Open stores every sender a block rule does not match. Allow list stores a sender only when the envelope or the From header matches an allow rule. A block match wins over an allow match.

A domain holds 1,000 rules. A message a rule refuses is not stored, and nothing is sent back to that sender. GET /emails/receiving/refusals counts those refusals per domain.

Turning receiving on

  1. Turn on receiving for the domain. Its records then include one MX record: <your domain> MX 10 inbound.agentisend-dns.com.
  2. Publish it with the lowest priority number of any MX on that name. A name whose mail is read somewhere else already should not get it: use a subdomain such as inbound.example.com.
  3. Add a webhook for email.received.

Messages up to 10 MB are accepted, for up to 20 recipients on your domain per message. Mail for a domain that is not verified, or has receiving off, is refused at the door and never stored.

Reading received mail

extracted_text is the reply with quoted history, a signature block, a "sent from my phone" line, an unsubscribe footer and a legal disclaimer removed. extracted_html is that same cut in HTML. Either field is null when it could not be produced, and an empty result is null too: read text, then html.

A forwarded message often arrives as a short note plus the original, marked the same way a reply marks quoted history. The extracted fields then keep the note and drop the forwarded message. Read text when you need what was forwarded.

A delivery-failure notice is kept whole, including the copy of the message that failed.

The list and the thread list do not include these fields. Each message is read on its own.

Every message in the list and the single read carries created_at, message_id, cc, reply_to and its attachments, as Resend's do. to is the address on your domain the copy was delivered to; the single read also lists it in received_for.

Attachments

Each attachment has a uuid id that stays the same on every read and in the email.received webhook. `GET /emails/receiving/{id}/attachments` gives each one a download_url that needs no API key and stops working at expires_at, one hour later. GET /emails/receiving/{id}/attachments/{attachment_id} returns the file itself, or the same JSON view when you ask for JSON (the Resend SDKs do). Files always download as plain bytes, whatever type the sender declared, so a hostile attachment cannot run in a browser.

That JSON view also carries text_url beside download_url for a PDF (the text layer only), a .docx document, a .xlsx spreadsheet, CSV, plain text, Markdown, JSON and HTML. text_url returns plain text and stops working at the same expires_at. It is null when the file has no text layer, is over 10 MB, or is another type. Extracted text stops at 250,000 characters.

Suspect mail

Every received message carries a verdict: clear, review, or unavailable. clear is ordinary mail. review means the message asks an assistant to ignore its instructions, hides text, carries a long encoded block, uses markup that marks a system role, or asks for an action from a Reply-To address that is not the From address. unavailable means the message is a bounce, has no text, or is larger than 256 KB, so it was not judged.

The body is still data. The verdict is a label, not a command, and nothing in it is followed.

A domain is in one of two modes, set with PATCH /domains/{id} and inbound_hold_mode:

  • Monitor (the default). The message is stored and email.received fires with inbound_verdict.
  • Hold. A review message is stored with held true. email.received waits. email.received.held fires instead, and the message appears in GET /agent-actions with kind inbound_release and in GET /emails/receiving?held=true.

POST /emails/receiving/{id}/release with a reason releases one held message. email.received fires once. A second release does not send it again. GET /emails/receiving/{id} returns a held message to the account that owns it. Inbox reads over MCP leave held messages out unless include_held is true.

Replying to mail received here

`POST /emails/receiving/{id}/reply` answers one received message. The recipient is the original sender, and the reply carries In-Reply-To and References taken from the stored message, so the customer's mail client files it under the same conversation. Budgets, the kill switch, suppressions and the sending-domain check all apply. Agents connected over MCP use the reply_to_email tool, which calls the same route.

Replying to mail received somewhere else

When your inbox lives elsewhere (a Gmail inbox, a help desk), send the reply with POST /emails and copy the threading headers from the message you are answering:

import { AgentiSend } from 'agentisend';

const agentisend = new AgentiSend(process.env.AGENTISEND_API_KEY);
await agentisend.emails.send({
  from: 'Support <help@acme.com>',
  to: 'customer@example.com',
  subject: 'Re: Where is my order?',
  text: 'It shipped this morning.',
  headers: {
    'In-Reply-To': '<CAB7xyz@mail.gmail.com>',
    References: '<root.1234@helpdesk.example> <CAB7xyz@mail.gmail.com>',
  },
});
  • In-Reply-To is the Message-ID of the message you are answering: 1 to 10 message IDs.
  • References is that message's own References followed by its Message-ID: 1 to 50 message IDs, each at most 250 characters and 4000 characters in all.
  • Each message ID is written in angle brackets, <left@right>, separated by spaces. A value in any other shape is refused, and the error names the header and the rule.
  • Message-ID may be set in headers when from is on a domain you have verified here: one message ID, not on agentisend.com. A help desk that mints its own ID and threads later replies on it keeps working. Without one, the message goes out with <id@agentisend.com>, where id is the id the send returned. Setting it, or List-Unsubscribe or List-Unsubscribe-Post, when that domain is not verified is domain_not_verified, and the message names the header. The same headers on the onboarding sender are invalid_parameter: the header cannot be set on the onboarding sender.