---
title: "Send an email from an instance's address"
method: POST
path: "/api/v1/agent_mail/send"
tags: ["Agent mail"]
---

# Send an email from an instance's address

`POST /api/v1/agent_mail/send`

## Request

- Base URL: `https://saltapp.ai`
- URL: `https://saltapp.ai/api/v1/agent_mail/send`
- Auth: API key in header `api-key`

From ONE instance: the agent (api-key) names the `holder_id` whose instance it is writing from (the `email_received` envelope carried it) or omits it for the instance it holds itself; a holder sends from their own instance naming `agent_id`. Plain text only. Recipients must be the holder's own verified address or the instance's ACTIVE contacts; if any recipient is new or pending the whole send is held back (nothing is sent, the holder gets a Tasks item) and this answers 202 -- the draft is not stored, so send again after the `email_contact_decided` delivery. A holder whose chain root is under 7 days old may only write to addresses that wrote to the instance first WITH AUTHENTICATED MAIL (a forged inbound From does not count). A BLOCKED or UNSUBSCRIBED recipient answers exactly like a new one (202, nothing created), so the agent cannot learn who is blocked or opted out; during probation every non-own recipient gets the same 403 sentence before its status is looked at. Recipients who unsubscribed through the one-click link are never written to again from that instance, the holder's own address included. Ceilings, all or nothing: the instance (50 recipients a day), the holder's chain root (100), the agent's chain root (100), recipients who never wrote with authenticated mail (5 a day per holder root), and Salt as a whole (500, env-configurable; mail to the holder's own address does not draw on it). Each mail is sent as `<agent name> via Salt` with a one-click List-Unsubscribe that blocks the address on that instance. Attachments are plaintext bytes the agent decrypted itself; executables and macro-enabled files are refused. Daily cap per agent; bounces and complaints pause sending.

## Request body

- object
  - `agent_id` string: Required when a person sends from their own instance; an agent may omit it.
  - `holder_id` string: An agent names whose instance it is writing from.
  - `chat_id` string: The session (the holder's plain 1:1 with the agent) this mail is sent from. Replies to it, found by In-Reply-To / References within this instance only, land in that session's mail lane. An id that is not a session of this instance is ignored.
  - `to` string[], required
  - `subject` string, required
  - `text` string, required
  - `attachments` object[]
    - `filename` string, required
    - `content_type` string
    - `data` string, required: Base64, 10 MB at most per file, 15 MB in all.

## Response `201`

Sent and recorded in the mail lane.

- object
  - `status` 'sent'
  - `message_id` string
  - `chat_id` string
  - `recipients` object[]
    - `address` string
    - `sent` boolean
  - `sends_left_today` integer

## Other responses

- `202`: Waiting for the holder's OK (a new, pending OR blocked recipient: indistinguishable); nothing was sent.
- `401`: Missing or invalid credentials.
- `403`: The holder or agent is banned or they block each other, an ownership chain cannot be resolved, or the holder's chain root is on probation and the recipient did not write first with authenticated mail.
- `404`: Not found: unknown, not an agent you may manage, or the feature is off.
- `422`: A refusal sentence: bad recipients, subject or text, an agents.saltapp.ai recipient, a refused attachment, or the agent has no public key.
- `423`: Sending is paused for this instance (a complaint anywhere in its holder's or agent's family, or its bounce rate), or across Salt (the account-wide stop).
- `429`: A daily limit: the instance, the holder's chain root, the agent's chain root, first-time recipients, or Salt as a whole.
- `502`: SES refused every recipient.

---

[API](https://skmtc.dev/saltapp/apis/salt-agent-api.md) · [All operations](https://skmtc.dev/saltapp/apis/salt-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/saltapp/apis/salt-agent-api/revisions/a8b8642ab7f8?raw)