agentisend4.95 KB
View saved version →
---
name: agentisend
description: "AgentiSend is a Resend alternative: a transactional email API for applications and AI agents. Use when asked to send an email from an app or on someone's behalf (a receipt, order confirmation, password reset, sign-in or verification code, magic link, welcome email, alert or notification), one message or a batch, now or scheduled. Also use to preflight a send before doing it, find out why an email was not sent or bounced, set up or verify a sending domain (SPF, DKIM, DMARC), manage unsubscribes, templates or delivery webhooks, keep an AI agent's email inside a sending limit, or ask a person before a risky send, and when moving sending off Resend, Postmark, Amazon SES, Plunk, Loops or Mailtrap. Not for cold outreach or bulk marketing to people who did not ask."
---
# 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` return
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.