agentisend4.54 KB
View saved version →
---
name: agentisend
description: AgentiSend is a transactional email API for applications and AI agents. Use when asked to send a receipt, password reset, sign-in code, alert or any transactional email, to check what an email send would do before doing it, to find out why an email was not sent or bounced, to set up or verify a sending domain, or to ask a person before a risky send.
---
# Sending email with AgentiSend
You are sending real mail to real people through the account the person
connected. Three things make that safe, and each is one tool call.
## 1. Before anything else: what may you do?
Call `whoami`. It returns the scopes you hold, the tools those scopes reach,
the budget remaining and when it refills, whether a kill switch is on, the
account's trust standing, and `can_send_now` as the summary. Read it before
the first send and again after any refusal.
If `can_send_now` is false, say why in the person's words and stop. A paused
key or an unverified domain is a decision someone made; retrying does not
change it.
## 2. Test the send before you make it
Run the payload through `preflight_email` first. It runs every gate a real
send runs (validation, sending domain, suppression, budget, loop guard, trust
standing, content scan), sends nothing, and costs nothing. A preflight that
comes back `ok: false` carries the same `code`, `message` and `fix` the
real send would have. Fix what `fix` names and preflight again.
Then `send_email`. Always pass `idempotency_key` when a retry is possible:
the same key returns the first result instead of sending twice. For many
different messages use `send_batch` (up to 500 items, one result each, in
order). For a later time pass `scheduled_at`; `cancel_email` and
`reschedule_email` change it.
An address ending in `@simulator.agentisend.com` costs nothing, reaches
nobody, and works before any domain is verified. Use it to show the person
what a send looks like.
## 3. When a send is risky, ask a person
Large recipient lists, unusual hours, anything irreversible, anything the
person said to check first: do not send and do not silently refuse. Call
`request_approval` with the payload and a reason. Nothing is sent and no
budget is spent. `list_agent_actions` tells you what the person decided and
why. No tool approves one, including for you.
## When you are refused
Branch on the error's `code` and `retryable`, never on the prose.
- `rate_limit_exceeded` or `rate_ceiling_exceeded`: the only class where
waiting works. Wait `retry_after_seconds` and repeat the same call.
- `agent_budget_exceeded`: the period's allowance is spent. A person raises
the number or the period rolls over. Do not retry in a loop.
- `kill_switch_active`: a person stopped this key. Tell them. Only they can
resume it.
- `approval_required`: the loop guard held this send. It is in the approvals
inbox; `list_agent_actions` shows its state.
- `trust_paused`: delivery outcomes moved the account down the ladder.
`get_trust_standing` explains each reason.
- `suppressed_recipient`: that address asked not to be contacted, or it hard
bounced. Do not remove the suppression to get around it.
- `domain_not_verified`: publish the DNS records from `get_domain`, then
`verify_domain` or `wait_for_domain`.
Everything else: read `fix`. It names the tool or the person. When nothing
obvious is wrong, `why_was_this_not_sent` lists every blocker on the key and
the account, with `is_normal_wait` to tell a scheduled send from a paused key.
## After the fact: what happened to that message?
`get_email` returns the message with its event timeline. `explain_email`
returns the verdict after a bounce or complaint, the evidence, whether the
identical send can be retried, and the remediation as steps you can call.
Follow those; do not invent an endpoint.
## Setting up a sending domain
`create_domain` registers the name. `get_domain` lists every DNS record
with host, type, value and whether it is required. The person publishes them
at their DNS provider; then `verify_domain` re-checks, or `wait_for_domain`
waits for the server's own checks. If an SPF record already exists on the
name, merge the value into it. A second SPF record invalidates both.
## What you cannot do here
- Lift a kill switch, or approve a held send.
- Read the contents of a message you were stopped from sending; you see
shapes (recipient counts, whether there is a body).
- Send unsolicited mail to people who did not ask for it. There is no tool
for it, and asking for one is out of scope.
## Reference
`references/errors.md` lists every refusal code, whether waiting helps, and
what to do.
Referenced files: 1 — file references are metadata, not package contents.
