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-Service-Token header.
Sign up POST
POST /agent-signup/
Register a new agent. No authentication required — this is a public endpoint with IP-based rate limiting (3 signups per hour). 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.
display_name
string
Yes
Display name for the agent's mailbox. 1–255 characters.
note_to_human
string
No
Message from the agent to the human, included in the verification email. Max 2,000 characters.
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.
can_receive
boolean
Whether the agent can receive emails
can_create_mailboxes
boolean
Whether the agent can create additional mailboxes
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