Email your human
POST /v1/inboxes/{id}/email-human lets the agent of a claimed account send one short plain-text email to the human who claimed it, for example “your table is booked” or “I need you to approve this”. Here there is no way to choose the recipient: it is always that human. An agent can also answer someone who wrote to its inbox, with the MCP tool reply_to_email (some accounts only).
Send it
Section titled “Send it”curl -s -X POST "https://api.replyz.io/v1/inboxes/$INBOX/email-human" \ -H "Authorization: Bearer $REPLYZ_API_KEY" \ -H "Content-Type: application/json" \ -d '{"subject":"Table booked for Friday","text":"I booked a table for two at 20:00. Reply to this email if you want a different time."}'The answer is 202 with {id, status: "queued", queued_at}. Queued does not mean delivered: the email can still fail, and the agent is not told. Do not tell your human that it was delivered.
- Only for a
claimedaccount. Asandboxaccount gets403not_claimed: ask your human to claim it first (how). - The recipient is always the human who claimed the account. A
to,ccorbccfield is ignored. If the human changed before the email was sent, the email is dropped. - At most 10 a day per human (UTC day), across all the agents they claimed:
429email_human_limit. subjectis 1 to 200 characters on one line;textis 1 to 10,000 characters of plain text. No HTML, no attachments. Invisible and control characters are removed.- The email comes from
inbox@youreplyz.com, and a reply from the human goes to the agent’s inbox, where it arrives like any other mail (and is untrusted: checksender_trust). The footer of the email says it was written by an AI agent, not by Replyz. - The MCP tool
email_my_humanand the CLI commandtell-humando the same thing (MCP, CLI; the CLI command works from version 0.2.0, which is on npm).
When it fails
Section titled “When it fails”| Code | Meaning | What to do |
|---|---|---|
not_claimed (403) |
The account is a sandbox | Ask your human to claim it |
sending_paused (403) |
Sending is paused for this account | Write to abuse@replyz.io if it is a mistake |
email_human_paused (403) |
The human marked an earlier email as spam, or mail to their address bounced or was rejected | Tell your human in your own chat. After a spam complaint, emailing your human stays off (if they think it is a mistake: abuse@replyz.io). After a bounce or rejection, they write to hello@replyz.io to turn it back on |
recipient_suppressed (409) |
The human’s address bounced or complained before | Tell your human in your own chat; they can write to hello@replyz.io |
email_human_limit (429) |
10 already today | Wait for Retry-After |
sender_quota (503) |
Replyz’s sending quota is used up for now | Wait for Retry-After |
sender_unavailable (503) |
Emailing humans is switched off, or paused for everyone after repeated complaints | Tell your human in your own chat; retry later |
After a bounce or a complaint, the account is paused first, so the answer is email_human_paused (403); recipient_suppressed (409) only shows when the address is on the suppression list and the account is not paused.
In every failure case, tell your human in your own chat or channel instead.
Replyz’s own emails
Section titled “Replyz’s own emails”Replyz also emails the human by itself: the claim confirmation, statements of reasons about a restriction on the account, and notices (for example 30 days before a change of the terms). These do not count toward the agent’s 10 a day.