AgentiSend

Purpose: read one message you sent, with its event timeline — queued, sent, delivered, bounced, complained. NOT for: working out what to DO about a bounce (explain_email), or finding an id (list_emails). Returns: the same message GET /emails/:id returns (from, to, cc, bcc, subject, html, text, tags, status, created_at and the rest), plus events in order. not_found means the id is not one of this account's; it is not retryable.

get_email

Purpose: read every event recorded for one sent message, oldest first, with the provider detail. NOT for: deciding what to do about a bounce (explain_email) or counting across many messages (get_metrics). Returns: data, has_more, and next_cursor. Each row has type, occurred_at, recipient, detail and provider_message_id.

get_email_events

Purpose: find out whether this key is stopped, since when, and the reason recorded. Read it when a send fails with kill_switch_active. NOT for: lifting it. Nothing here can; a person resumes a key in the console. Returns: paused, paused_at, the reason, and where a person goes to undo it.

get_kill_switch_state

Purpose: see how much of this key's send budget is left, when it refills, and its per-minute ceiling. Read it before a batch, and after an agent_budget_exceeded refusal. NOT for: changing any of it. Raising is the account owner's. Returns: budget, consumed, remaining, the period and when it resets, and the per-minute ceiling with its current window.

get_agent_budget

Purpose: read the account's standing — ok, warning, throttled or paused — and the reasons behind it. Check it first when a send fails with trust_paused. NOT for: changing it. Standing follows delivery outcomes; nobody sets it directly. Returns: the state, each reason with its metric, value, threshold and window, and when it is next reviewed.

get_trust_standing

Purpose: see which assistants are connected to this account, and when they last used the connection. NOT for: an assistant acting on its own. This is a person’s list. A key is refused with human_action_required. Returns: data, has_more, and next_cursor. Each row has id, client_id, client_name, scopes, created_at and last_used_at.

list_oauth_grants

Purpose: see the saved groups of contacts, the rules that define them, and how many people each currently matches. NOT for: sending to one. Who receives a broadcast is a person's decision. Returns: each segment with its rules and current size.

list_segments

Purpose: look up the people this account already has a relationship with. Pass an email to find one. NOT for: finding addresses to contact for the first time. This product has no feature for that and will not grow one. Returns: each contact with its properties, newest first.

list_contacts

Purpose: find messages, newest first. Filter by status, sender, recipient (to, cc or bcc), tag, domain or a search string — the same filters GET /emails takes. NOT for: analytics or counting — it pages rows, it does not aggregate. Returns: data, has_more, and next_cursor. Page again by passing next_cursor as cursor; when has_more is false you have everything.

list_emails

Purpose: read your held actions in any state — pending, approved, rejected, killed — and find out what a person decided and why. NOT for: reading what a held message said; tools see shapes, not contents. Returns: each action with its state, decision time, the reason given, and a shape of its payload. Filter by state, or omit it for everything. list_pending_approvals is this list narrowed to what is still waiting.

list_agent_actions

Purpose: see which of your actions are waiting on a person, newest first. NOT for: deciding one — no tool approves or rejects — or reading a held message's contents, which stay out of reach by design. Returns: each action's id, kind, age and a shape of what it holds: recipient counts, whether there is a subject, whether there is a body.

list_pending_approvals

Purpose: read mail that arrived at this account’s domains, newest first. Filter by recipient, sender, or a search string. NOT for: mail you sent (list_emails), grouping a conversation (list_threads), or sending a reply (reply_to_email). Returns: data, has_more, and next_cursor. Page again by passing next_cursor as cursor; when has_more is false you have everything.

list_received_emails

Purpose: group received mail into conversations by Message-ID, In-Reply-To and References, newest thread first. NOT for: reading a message body (get_received_email) or sending a reply (reply_to_email). A thread with no Message-ID is listed under its own received id. Returns: data, has_more, and next_cursor. Each row has the thread id, subject, participants, message_count, last_received_at and latest_id.

list_threads

Purpose: see the domains this account can send from and where each one stands. Call it before sending from an address you have not used. NOT for: the DNS records of one domain (get_domain) or re-checking them (verify_domain). Returns: each domain with its id, region, status and when it last verified.

list_domains

Purpose: see which addresses this account will not send to, and why each one is on the list. Pass an email to read that one row, including its id. NOT for: a general contact list (list_contacts). Returns: each row with its id, address, level, origin (bounce, complaint or manual), source_id, stream, and platform. platform true means the row applies to every account. Filter with origin when you only want one of those three.

list_suppressions

Purpose: see the templates on this account and which version of each is live. NOT for: rendering one (render_template) or making a draft live (publish_template). Returns: each template with its current published version number. One with no published version cannot be sent yet.

list_templates

Purpose: see where events are delivered, what each endpoint subscribes to, and whether it is disabled. NOT for: reading signing secrets. They are shown once at creation and never again — a listing that returned them would let every reader forge deliveries. Returns: each endpoint with its url, events and state.

list_webhooks

Purpose: move a scheduled — or canceled — message to a new send time. NOT for: a settled message. Sent, bounced, failed, complained and suppressed cannot be moved, and the refusal names the status. Returns: the message id, its status and the new scheduled time.

reschedule_email

Purpose: find out exactly what a send would do, without doing it. Runs every gate a real send runs — validation, sending domain, sandbox, trust, suppression, budget, loop guard, content scan. NOT for: sending. Nothing leaves and no budget is spent, ever. Free and unlimited on purpose. Returns: the same ok/error POST /emails would return for the same payload, plus each gate's own verdict, and simulated: true when every recipient is a simulator address. The arguments are the same ones send_email takes: copies, headers, attachments, an inline image content_id, a template and a topic.

preflight_email

Purpose: make a template's draft the version send_email uses. NOT for: editing. Published versions are immutable; publishing again makes the next one, so nothing already sent can change under you. Returns: the template id and the new version number.

publish_template

Purpose: re-read the public DNS for a domain and report which records are in place. NOT for: creating records. Publishing DNS is done wherever the domain is hosted, by whoever runs it. Returns: the same domain view GET /domains/:id returns after the check — every record with status, host, value_strings, required and observed. A domain with nothing published yet stays pending rather than failing: DNS takes minutes to a day or two to spread, and calling that a failure would make you give up on a domain that is about to work. Pass the domain id or the domain name as domain_id. id and name mean the same thing.

verify_domain

Purpose: register an endpoint to receive event deliveries. NOT for: retrieving a secret you lost. Store the signing secret when you get it. Returns: the endpoint and its signing secret, ONCE. Verifying that signature is the only way a receiver can tell a real delivery from anything else.

create_webhook

Purpose: remove an endpoint for good. Deliveries stop immediately and its history stops being reachable. NOT for: pausing one. Disabling keeps the endpoint and its secret; delete it when it is genuinely gone. Returns: the id and confirmation it is gone. Nothing is re-delivered elsewhere.

delete_webhook

Purpose: see exactly what a template produces with your values, and find out which variables it needs. NOT for: sending. Nothing leaves. Returns: the rendered HTML. An unknown or missing variable comes back named, with the fix, instead of shipping a half-filled email.

render_template

Purpose: reply to one received email. Sets In-Reply-To and References so the conversation threads, and runs every send check a new send runs. NOT for: a new conversation (send_email), or reading the original (get_received_email). The recipient is the first Reply-To address, else the first From address; any other addresses in those headers are left off, so pass them as cc if they should get the reply. from defaults to the address that received it. Returns: the outbound message id and its status. Delivery happens after; get_email has the outcome. Refusals are the same as send_email: domain_not_verified, suppressed_recipient, agent_budget_exceeded. Addresses ending in @simulator.agentisend.com cost nothing. Sending twice is sending twice: pass an idempotency_key and a retry returns the first message id instead of a second email.

reply_to_email

Purpose: disconnect one assistant. Every token it holds, and the key behind them, die immediately. NOT for: an assistant acting on its own. A key is refused with human_action_required. Do this in the console Connections page. Returns: the connection id and deleted: true. Repeating the call on an already-revoked id is not_found.

revoke_oauth_grant

Purpose: send one email now, or at a time you name. Takes one recipient or a list. Each To, CC and BCC recipient counts as one email. NOT for: checking whether a send would work (preflight_email), sending many different messages at once (send_batch), or asking a person first (request_approval). Returns: the message id and its status, immediately. Delivery happens after; get_email has the outcome. Refusals name the gate and the cure: validation_error lists the bad fields, domain_not_verified points at verify_domain, suppressed_recipient says the address asked not to be contacted. Addresses ending in @simulator.agentisend.com cost nothing, reach nobody, and work before any domain is verified. from onboarding@agentisend.com delivers real mail only to this account's member sign-in addresses, 20 per UTC day, with no cc, bcc, attachments, tracking, or extra headers. Sending twice is sending twice: pass an idempotency_key and a retry returns the first message id instead of a second email.

send_email

Purpose: send up to 500 different messages in one call, the same ceiling as POST /emails/batch. Each item takes the same fields as send_email, including headers and attachments. NOT for: one message to many recipients — that is send_email with a list of addresses. Each To, CC and BCC recipient counts as one email. Returns: sent, failed, and one result per item IN THE ORDER YOU SENT THEM, each carrying the same code and fix a single send would have given. One bad address does not fail the batch. Each accepted item costs its own recipient count, and each To, CC and BCC recipient counts as one email. Pass an idempotency_key: a retried batch without one sends every accepted item again.

send_batch

Purpose: stop sending to an address, or to a whole domain (pass "@example.com"). Use it the moment someone asks not to be contacted. NOT for: undoing one (remove_suppression). Returns: the row that now blocks that address. Adding is always allowed and always safe; it is the direction that protects the account.

add_suppression

Purpose: wait until a sending domain is verified or failed, without re-checking DNS yourself. Pass the id or the domain name as domain (name means the same thing). timeout=0 is a snapshot of the last check. NOT for: publishing DNS, or forcing a new lookup (verify_domain). The server keeps checking on its own for 72 hours. Returns: status, next_poll_seconds (when the server will check again), deadline (when the 72-hour window closes), reason, and progress (required_verified of required_total). If it is still pending, call again after next_poll_seconds, or send to an address ending in @simulator.agentisend.com meanwhile.

wait_for_domain

Purpose: the one read to make before deciding anything, and again after any refusal. Answers who you are and what you may do. NOT for: changing anything. Returns: the account and key, the scopes held, the tools those scopes can call, budget consumed and remaining with its refill time, the per-minute ceilings, whether the kill switch is down, the account trust standing, can_send_now as the summary for real recipients, can_send_to_simulator for test sends to @simulator.agentisend.com addresses, capacity.per_mail_system_per_hour (this account's own cap for one receiving mail system; 10 until the account is 7 days old) and capacity.shared_pool_per_mail_system_per_hour (all customers together), pending_approvals: sends from this key waiting for a person, which hold only those sends, test_send: before a domain verifies, the address a first test goes from and the account's own addresses it can go to, and sending_domains.limit: how many verified sending domains this plan may hold (null when the plan has no cap).

whoami

Purpose: find out what is holding a send. Name an email_id for one message, or omit it to ask what is blocking this key and this account right now. NOT for: the outcome of a delivered message (get_email) or what to do about a bounce (explain_email). Returns: every blocker, each with why, the fix, and is_normal_wait — the field that matters, because a scheduled send and a paused key look identical without it. When nothing is blocking, it says so and says what it checked rather than implying a message exists.

why_was_this_not_sent