Receiving and replying

Mail that arrives at your domains is stored and announced with an email.received event. Every message can be read as data, grouped into conversations, and answered through the same checks a new send runs.

Reading received mail

• `GET /emails/receiving` lists received mail, newest first, filtered by recipient, sender or date range.
• `GET /emails/receiving/threads` groups it into conversations by Message-ID, In-Reply-To and References.
• `GET /emails/receiving/{id}` returns one message: its headers, its text and HTML bodies, and the attachments it carried.

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 is always ours. It is what a reply to your message threads on when it comes back here, so it cannot be set in headers.