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's mailbox. 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.
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.
JSON
cURL