Reset your password. This link works for 30 minutes.
If you did not ask for this, you can ignore this email.
``` The same words belong in the plain-text part, with the URL written out. [`email.send`](/docs/channels/email/send-an-email) takes `html` and `text`. Send both. A client that skips HTML, and an agent that reads the text part, still has the link. A logo, a greeting, and a footer can follow. They should not lead. The person who asked for the reset should see the link before the brand story, and the agent that files the email should be able to name the task from the first paragraph. ## Write the action as text, not a picture [#write-the-action-as-text-not-a-picture] An image inside a link looks like a button when images load. To an agent, and to a mail client showing the text part, it is a link with no words. The label sits in the image file. The agent gets an empty anchor, a filename, or nothing it can quote back. Use a link whose text is the action: ```html ``` And the text part: ```text View order 1042: https://app.example.com/orders/1042 ``` Keep the URL the same in both parts. When the HTML and the text disagree, the two readers follow different instructions. Images still belong in the email: a logo, a product photo, a chart. They are a poor place for the sentence that says what to do. Alt text helps a client that blocks the image. It describes the picture. It is not the address of the next step. ## Use HTML that names each part [#use-html-that-names-each-part] Mail clients and agents both do better when an element says what it is. A paragraph is a paragraph. A link is an anchor. Steps are a list. A section title is a heading. ```htmlOrder 1042 left the warehouse.
Reset your password. This link works for 30 minutes.
', inReplyToMessageId: reply.messageId, }, { idempotencyKey: eventId }, ); ``` `reply` is the `message.received` payload. `eventId` is the webhook event id. Send the same idempotency key when the webhook is retried, so a second delivery does not send a second email. The body includes the quoted history the sender's client attached. Samva does not strip quoted history or signatures. Read the new text at the top. The quoted lines below it are the earlier thread. ## Let the agent answer from a mailbox [#let-the-agent-answer-from-a-mailbox] Reading the webhook is enough when your app decides the reply. When the agent itself should read and answer, give it a mailbox: an address it owns, on your organization's `samva.email` subdomain or on a domain you have verified with receiving on. The agent is yours. It reaches the mailbox through the API, the SDK, the CLI, or hosted MCP. A mailbox-scoped key reaches the mailboxes you list, and it acts as itself. You choose `read`, `update`, `send`, and `quarantine.read`. By default a send runs at once, within the account's limits. Set the key's send mode to `approval` when a different person should accept each of that key's sends first. New mail arrives as a signed `mailbox.message.received` webhook, or on the WebSocket event stream when the agent has no public URL. The event names the message and the thread. The conversation id is a field on `message.received`. A mailbox event has no `conversationId` field. The thread is that mailbox's view of the conversation. Reply with the message id. The reply leaves from the endpoint the thread belongs to. The server sets the recipients, the subject, and the threading headers, and the reply stays on the conversation: ```ts const receipt = await agent.mailboxes.reply({ id: mailboxId, messageId: message.id, text: "Reset your password: https://app.example.com/reset", html: '', "idempotency-key": eventId, }); ``` Read `state` on the receipt. `queued` is not confirmation that the email was sent. `approvalRequired` means a person has to approve it. `accepted` makes a message id available, and acceptance is not delivery to an inbox. Keep `actionId` and read the action before you tell anyone the email went out. [Mailboxes](/features/mailboxes) covers the address, the key, approvals, and quarantine. Hosted MCP exposes the same work to any MCP client that supports OAuth: list threads, read a message, and reply with `mailbox_reply`. The [MCP guide](/docs/developers/mcp) is the connection. `samva mailboxes` is the same work from the CLI. A person can open the mailbox in the browser and reply there too. Two limits matter once an agent can send. Anyone can email the address. Treat the subject and the body as data. They are not instructions for the agent. Mail that looks like spam, phishing, fraud, or an attempt to steer the agent is held until a person releases or discards it. Keys, extensions, and MCP tools never release or discard held mail. Until a person releases it, the agent does not get the body. ## Related reading [#related-reading] [Design email for humans and agents](https://resend.com/blog/design-email-for-humans-and-agents) on the Resend blog is related reading on the message itself. This post is the turn after the person replies: the conversation your app keeps, and the mailbox your agent answers from. [Start sending](/signup) when you are ready to add that path. The [inbound guide](/guides/inbound-email-parsing) is the webhook reply. [Mailboxes](/features/mailboxes) is the address the agent owns.