These endpoints handle the agent side of signup — self-registration, verification, and status checking. The initial signup endpoint requires no authentication. All other endpoints require the API key returned from signup, passed in the X-API-Key header.
Sign up POST
POST /agent-signup/
Register a new agent. No authentication required — this is a public endpoint with IP-based rate limiting. Returns a provisional identity with a mailbox address and API key. The API key is shown only once and must be stored securely.
Request body
Field
Type
Required
Description
human_email
string
Yes
Email of the human who oversees this agent.
note_to_human
string
Yes
Message from the agent to the human, included in the verification email. 1-2,000 characters.
display_name
string
No
Display name for the agent identity. 1-255 characters. Defaults to the generated or supplied handle when omitted.
agent_handle
string
No
Optional agent handle override. A leading @ is stripped automatically.
email_local_part
string
No
Optional mailbox local part to use before @inkboxmail.com. If omitted, the server generates one.
Request example
JSON
Response (201)
JSON
The api_key is returned only in this response. Store it immediately, because it cannot be retrieved again.
After signup, your agent has both a mailbox and a tunnel. Self-signup provisions an edge-mode tunnel alongside the mailbox; the new agent is reachable at my-agent.inkboxwire.com from day one. The wire shape of AgentSignupResponse is unchanged — just be aware that the tunnel exists.
Submit the 6-digit verification code that the human received by email. On success, the agent's status changes to agent_claimed and full sending capabilities are unlocked.
Request body
Field
Type
Required
Description
verification_code
string
Yes
6-digit numeric code from the verification email
Request example
JSON
Response (200)
JSON
Error responses
Status
Description
401
Invalid verification code
404
Agent identity not found
410
Verification code expired (codes expire 48 hours after generation)
429
Too many verification attempts (max 5 per agent)
Code examples
cURL
Resend verification POST
POST /agent-signup/resend-verification
Resend the verification email to the human. Generates a new 6-digit code (invalidating the previous one). There is a 5-minute cooldown between resend requests.
Response (200)
JSON
Error responses
Status
Description
404
Agent identity not found
429
Cooldown not elapsed (5 minutes between resends)
Code examples
cURL
Check status GET
GET /agent-signup/status
Check the agent's current claim status, the agent owner's (human's) account state, and the agent's behavioral restrictions.
Response (200)
JSON
Response fields
Field
Type
Description
claim_status
string
agent_unclaimed, agent_claimed, or agent_rejected
human_state
string
human_no_account, human_account_unverified, or human_account_verified
human_email
string
The agent owner's email address
restrictions
object
Current behavioral restrictions (see below)
restrictions fields
Field
Type
Description
max_sends_per_day
integer
Maximum emails the agent can send per day (10 unclaimed, 500 claimed)
allowed_recipients
array
List of allowed recipient emails. Empty array means unrestricted.
can_receive
boolean
Whether the agent can receive emails
can_create_mailboxes
boolean
Legacy compatibility flag, currently always false — mailboxes are owned 1:1 by an agent identity and provisioned at identity-create time, so there is no standalone create-mailbox operation
Code examples
cURL
Response objects
AgentSignupResponse
Field
Type
Description
email_address
string
The agent's new mailbox address (e.g. sales-agent-a1b2c3@inkboxmail.com)
organization_id
string
Provisional organization ID (format: org_agent_<uuid>)
api_key
string
API key for the agent. Returned only once — store it securely.
agent_handle
string
Unique handle for the agent (format: <name>-<6-char-hex>)
claim_status
string
Always agent_unclaimed at signup
human_email
string
The agent owner's email address
message
string
Status message describing restrictions and next steps
JSON
cURL