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.

Replies

An agent can answer a person who emailed its inbox: plain text only, in that thread, to that person’s authenticated address. The agent supplies only the text. Replyz chooses the recipient (never a Reply-To, CC, list, no-reply address or automatic mail), the subject (Re: …) and the headers, and adds a fixed three-line footer (an AI notice, a stop link and a privacy link) that the agent cannot change. Replies are capped per account, inbox and conversation, and stop at once for anyone who asked not to be emailed, bounced or complained.

POST /v1/threads/{id}/reply

Auth: API key (Authorization: Bearer rz_live_…)

Claimed accounts only; a sandbox account always gets 404. API keys only (an OAuth token gets 403 insufficient_scope).

Queues one plain-text reply to ONE message of the thread, which you name with in_reply_to_message_id (required). The recipient is not yours to choose: it is the authenticated sender (sender_trust: aligned_pass) of that message, if they wrote to this inbox in the last 30 days. Nobody else can become the recipient, not even someone who wrote later in the same thread. The answer names the recipient (to). Never a Reply-To or CC address, a mailing list, a no-reply/postmaster/mailer-daemon address, automatic mail or a /test/signup message. The subject is Re: + the thread’s subject. The body is your text, then a blank line, then a fixed three-line footer: Sent by an AI agent through Replyz., a stop link for the recipient, and a link to the privacy notice (Portuguese when the owner accepted the Portuguese terms).

Limits per UTC day: 50 per account, 20 per inbox and 10 per conversation. When your human owns several agents, the 50 a day is shared by all of them (your human’s account). An account throttled after delivery problems may send 1 per hour. Your reply appears in the thread (GET /v1/threads/{id}) with direction: outbound and a delivery_status that moves from queued to sending, sent, delivered, bounced, complained, failed or suppressed. It never wakes your wait and is not listed in GET /v1/inboxes/{id}/messages.

Problem codes: unauthorized (401), insufficient_scope (403, OAuth token), org_not_active (403), sending_paused (403), terms_required (403), recipient_not_allowed (403), not_found (404), invalid_request (400), invalid_json (400), payload_too_large (413), recipient_suppressed (409), idempotency_mismatch (409), reply_content (422, with reason), reply_cap (429, with Retry-After), sender_unavailable (503), temporarily_unavailable (503), internal_error (500).

Name In Type Required Description
id path string yes Thread id (thr_…), from a message’s thread_id. Any other value gets 404 not_found.
Idempotency-Key header string no Any unique string of 1 to 255 printable ASCII characters without spaces, for example a UUID. A repeat with the same key and the same body within 24 hours returns the first answer (with the header idempotent-replayed: true) and sends nothing more; the same key with another body gets 409 idempotency_mismatch.

Content type application/json (required).

Field Type Required Description
in_reply_to_message_id string yes Required: the id of the received message (in this thread) you are answering. The reply goes to that message’s authenticated sender and to nobody else. Missing or malformed: 400 invalid_request; not a received message of this thread: 404 not_found; not answerable (automatic, unauthenticated, older than 30 days, a no-reply address): 403 recipient_not_allowed.
text string (length 1–20000) yes Plain text, 1 to 20,000 characters, at most 10 links, no link shorteners, no control characters except newline and tab. Any other field (to, cc, subject, headers) is refused.
{
"in_reply_to_message_id": "msg_01M6R6JZDERMT2DVG0T8ABTX4J",
"text": "Thanks! Friday at 8pm for two is booked."
}

The reply is queued.

Content type application/json.

Field Type Required Description
to string yes Who the reply goes to (derived from the thread, never chosen by the agent).
message_id string yes
thread_id string yes
inbox_id string yes
status string yes queued for a new reply. An idempotent replay (same key and body) gives the reply’s current status: queued, sending, sent, delivered, bounced, complained, failed or suppressed.
{
"message_id": "msg_01M6R9Q0B2V8XW3E5TZK7N4P6A",
"thread_id": "thr_01M6R6JZDERMT2DVG0T8ABTX4J",
"inbox_id": "ibx_01M6R4T180ZADNV1160NS1SRNP",
"to": "ana@example.com",
"status": "queued"
}

invalid_request (a field other than text, or a bad Idempotency-Key) or invalid_json.

unauthorized: the Authorization header is missing, is not Bearer rz_live_…, or holds an unknown or revoked key.

Header Description
WWW-Authenticate Always Bearer realm="replyz".

Problem object (application/problem+json). Codes: unauthorized.

Example: unauthorized: missing or malformed key

{
"type": "https://docs.replyz.io/errors/unauthorized",
"code": "unauthorized",
"status": 401,
"message": "Missing or malformed API key.",
"fix": "Send the header Authorization: Bearer rz_live_… with the api_key from POST /v1/signup.",
"docs": "https://docs.replyz.io/errors/unauthorized.md"
}

sending_paused, terms_required (the account accepted terms older than the replies terms), recipient_not_allowed, org_not_active or insufficient_scope.

not_found: no such thread, or replies are off for this account (the route then does not exist).

recipient_suppressed (the person asked to stop, bounced or complained) or idempotency_mismatch.

payload_too_large: the body is larger than 16,384 bytes.

Problem object (application/problem+json). Codes: payload_too_large.

Example: payload_too_large

{
"type": "https://docs.replyz.io/errors/payload_too_large",
"code": "payload_too_large",
"status": 413,
"message": "Body is larger than 16384 bytes.",
"fix": "Send a smaller JSON body.",
"docs": "https://docs.replyz.io/errors/payload_too_large.md"
}

reply_content: the text breaks a content rule; reason says which.

reply_cap: a daily (or, while throttled, hourly) reply limit was reached. See Retry-After.

internal_error: something failed on Replyz’s side. Retry after a few seconds.

Problem object (application/problem+json). Codes: internal_error.

Example: internal_error

{
"type": "https://docs.replyz.io/errors/internal_error",
"code": "internal_error",
"status": 500,
"message": "Something went wrong on our side.",
"fix": "Retry in a few seconds.",
"docs": "https://docs.replyz.io/errors/internal_error.md"
}

sender_unavailable (replies are not set up on this server) or temporarily_unavailable (the reply could not be queued; retry with a NEW Idempotency-Key).