Inboxes

An inbox is an email address on youreplyz.com that belongs to one account. Mail sent to it is stored for the agent to read. Signup creates the first inbox; the agent can list, view, label, create and delete inboxes.

Addresses

• Form: <slug>-<6 random characters>@youreplyz.com, all lowercase, for example scout-agent-kncx62@youreplyz.com.

• The slug comes from name (POST /v1/inboxes), or else from the account’s agent_name, or else from agent. Accents are removed, letters lowercased, every run of other characters becomes one hyphen, leading and trailing hyphens are dropped, and the result is cut to 20 characters. A slug shorter than 3 characters gets the prefix agent-.

  Name	Slug
  Scout Agent!	scout-agent
  Ação Rápida	acao-rapida
  x	agent-x
  测试	agent

• The 6 random characters are lowercase letters and digits.

• The address cannot be chosen beyond the slug, and cannot be changed later. name is not stored.

• Addresses are case-insensitive. There is no sub-addressing: scout-agent-kncx62+news@youreplyz.com is a different, unknown address.

Addresses are never reused

Before an address is issued, it is checked against every address ever issued. Deleting an inbox leaves a permanent record of the address (a keyed hash, not the address itself), so the address is never issued again, to anyone. Nobody can receive mail, such as a password reset, meant for a deleted inbox.

Reserved names

A name whose slug is reserved is refused with name_reserved, at signup (agent_name) and when creating an inbox (name):

• Role words such as postmaster, abuse, admin, security, billing, support, noreply and no-reply: refused as the whole slug and as one of its hyphen-separated words (support-bot is refused, supportbot is allowed).
• Broader role words such as info, mail, help, contact, sales: refused only as the whole slug (help is refused, help-desk-bot is allowed).
• Brand names such as paypal, google, microsoft, apple, amazon and banks or carriers. Long brand names are refused anywhere in the slug (googlebot); short ones only as a whole word (ups-tracking is refused, startups is allowed).
• Look-alikes of all of these, such as g00gle, rnicrosoft or paypaI.

The lists can change without an API change.

Limits

	Sandbox	Claimed (not available yet)
Live inboxes per account	1	3
Inbox creations per account per UTC day, the signup inbox included	3	10

• Over the live-inbox limit: 409 inbox_limit. Deleted inboxes do not count.
• Over the daily cap: 429 inbox_create_limit, with Retry-After until 00:00 UTC. A refused request does not count.
• So on its signup day a sandbox account can delete its inbox and create a new one twice, but it never has more than 1 live inbox.

Create, label, delete

Create an inbox (an optional Idempotency-Key makes a retry safe):

curl -s -X POST https://api.replyz.io/v1/inboxes \
  -H "Authorization: Bearer $REPLYZ_API_KEY" -H 'content-type: application/json' \
  -H 'Idempotency-Key: 4f9c2d1e-0b7a-4c55-9a1e-3b2f6d8e7c10' \
  -d '{"name":"travel","display_name":"Travel bot"}'

{"id":"ibx_01M6QTD0NZGBSW2A2HEQHTK37N","address":"travel-zow5el@youreplyz.com","display_name":"Travel bot","created_at":"2026-11-06T06:58:07.679Z"}

• display_name is a label for the agent’s own use (at most 64 characters). Nothing else uses it.
• Idempotency-Key: 1–255 printable ASCII characters (a UUID works), kept per account for 24 hours. A repeat after success returns the first response with the header idempotent-replayed: true and creates nothing. While the first request is still running, a repeat gets 409 idempotency_in_progress. After a failure, the key is released and a retry runs again.

Change the label (null or an empty string clears it):

curl -s -X PATCH https://api.replyz.io/v1/inboxes/ibx_01M6QTC7CS22K8B68968B2BMTX \
  -H "Authorization: Bearer $REPLYZ_API_KEY" -H 'content-type: application/json' \
  -d '{"display_name":"Scout (travel)"}'

{"id":"ibx_01M6QTC7CS22K8B68968B2BMTX","address":"scout-agent-kncx62@youreplyz.com","display_name":"Scout (travel)","created_at":"2026-11-06T06:57:41.776Z"}

Delete an inbox:

curl -s -X DELETE https://api.replyz.io/v1/inboxes/ibx_01M6QTC7CS22K8B68968B2BMTX \
  -H "Authorization: Bearer $REPLYZ_API_KEY"

{"id":"ibx_01M6QTC7CS22K8B68968B2BMTX","address":"scout-agent-kncx62@youreplyz.com","deleted":true,"deleted_at":"2026-11-06T06:58:07.580Z"}

Deleting:

• hides all mail of the inbox at once, from every read route and from the event feed;
• rejects mail to the address from then on;
• cannot be undone: a deleted inbox cannot be restored and its address is never issued again;
• works in every account status, also on an expired account. A second DELETE answers 404.

If the call answers 500, the inbox stayed live: repeat the DELETE.

Not available yet

• Sending from an inbox (replies, email to the human owner). Not available in the first release.
• Claiming the account to get 3 inboxes. Coming soon.

Not offered: custom domains, other shared domains, choosing or renaming the full address, aliases, sub-addressing, forwarding, webhooks.

Reference: Inboxes API.