Skip to content
Signups are open. https://api.replyz.io is live. Replies, paid plans and custom domains are not available yet, and details may still change.

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).

Terminal window
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 claimed account. A sandbox account gets 403 not_claimed: ask your human to claim it first (how).
  • The recipient is always the human who claimed the account. A to, cc or bcc field 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: 429 email_human_limit.
  • subject is 1 to 200 characters on one line; text is 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: check sender_trust). The footer of the email says it was written by an AI agent, not by Replyz.
  • The MCP tool email_my_human and the CLI command tell-human do the same thing (MCP, CLI; the CLI command works from version 0.2.0, which is on npm).
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 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.