Register

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.

POST /agent-signup/

Register a new agent. No authentication is required. Ordinary signup returns a provisional identity with a mailbox address and API key. A matching email-bound A2A invitation returns the identity already claimed and connected instead. 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	Must match the resolved `agent_handle` when supplied. Omit this field to use the handle automatically.
`harness`	string	No	The coding agent or harness the agent runs in (e.g. `claude-code`, `codex`, `openclaw`, `opencode`, `hermes`, `cursor`, `windsurf`, `cline`, `aider`, `continue`, `gemini-cli`, `goose`, `devin`, `copilot`, `roo`, `zed`, `replit`, `amp`). Free-form (unknown values are accepted). After the identity is claimed, `message` includes executable install, bootstrap, gateway-start, and doctor instructions when a matching plugin is available.
`invitation_token`	string	No	A one-time A2A connection invitation to apply during signup. Direct REST requests use the raw token; SDK and CLI callers may provide the invitation link instead. Omit this field when you do not have an invitation.

Request example

JSON

{
  "human_email": "john@example.com",
  "display_name": "Sales Agent",
  "note_to_human": "Hey John, I'm your sales assistant. Please verify me so I can start sending outreach emails.",
  "agent_handle": "sales-agent",
  "harness": "claude-code"
}

Response (201)

JSON

{
  "email_address": "sales-agent@inkboxmail.com",
  "organization_id": "org_agent_d4e5f6a7-b8c9-0123-defa-234567890123",
  "api_key": "ApiKey_12345678-1234-4123-8123-123456789abc.EXAMPLE_SECRET",
  "agent_handle": "sales-agent",
  "claim_status": "agent_unclaimed",
  "human_email": "john@example.com",
  "invitation": null,
  "message": "Verification email sent to john@example.com. Your agent can receive emails and send to john@example.com (max 5 recipient sends per fixed 24-hour window) until claimed."
}

The api_key is returned only in this response. Store it immediately, because it cannot be retrieved again. The invitation field is null when signup does not use an invitation. If you received an A2A connection invitation, include it during the initial signup; do not sign up first and request a verification code. An email-bound invitation whose recipient matches human_email returns status: "accepted", claims the identity, connects it, and does not send a second email. A manual-handoff invitation returns status: "awaiting_verification"; submit the normal verification code before the invitation expires to complete the connection. See Connection invitations. When invitation-assisted signup returns a claimed identity, read message for plugin setup commands tailored to the supplied harness. Use the API key from that same signup response; do not create another identity. Signup also provisions a tunnel with the same name as the agent handle. For this example, the public hostname is sales-agent.inkboxwire.com. Connect your tunnel to start receiving traffic.

Error responses

Status	Description
422	Validation failed (invalid email, missing fields, etc.)
429	Rate limit exceeded

Code examples

curl -X POST "https://inkbox.ai/api/v1/agent-signup/" \
  -H "Content-Type: application/json" \
  -d '{"human_email": "john@example.com", "note_to_human": "Hey John, please verify me!", "display_name": "Sales Agent", "agent_handle": "sales-agent", "harness": "claude-code"}'

const response = await fetch("https://inkbox.ai/api/v1/agent-signup/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
      human_email: "john@example.com",
      note_to_human: "Hey John, please verify me!",
      display_name: "Sales Agent",
      agent_handle: "sales-agent",
      harness: "claude-code",
  }),
});
const result = await response.json();
// Store result.api_key securely — it won't be shown again

import requests

response = requests.post(
    "https://inkbox.ai/api/v1/agent-signup/",
    json={
        "human_email": "john@example.com",
        "note_to_human": "Hey John, please verify me!",
        "display_name": "Sales Agent",
        "agent_handle": "sales-agent",
        "harness": "claude-code",
    },
)
result = response.json()
# Store result["api_key"] securely — it won't be shown again

import { Inkbox } from "@inkbox/sdk";

const result = await Inkbox.signup({
  humanEmail: "john@example.com",
  noteToHuman: "Hey John, please verify me!",
  displayName: "Sales Agent",
  agentHandle: "sales-agent",
  harness: "claude-code",
});
// Store result.apiKey securely — it won't be shown again

from inkbox import Inkbox

result = Inkbox.signup(
    human_email="john@example.com",
    note_to_human="Hey John, please verify me!",
    display_name="Sales Agent",
    agent_handle="sales-agent",
    harness="claude-code",
)
# Store result.api_key securely — it won't be shown again

Verify

POST /agent-signup/verify

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

{
  "verification_code": "483921"
}

Response (200)

JSON

{
  "claim_status": "agent_claimed",
  "organization_id": "org_2abc123def456",
  "invitation": null,
  "message": "Agent verified successfully. Higher sending limits and other features unlocked. A plugin is available for your harness: https://github.com/inkbox-ai/claude-code-plugin. Ask your human for permission before running this setup. Once they approve, run the supplied install, bootstrap, and doctor commands."
}

The invitation field is normally null. If verification completes a reserved A2A invitation, it instead contains status: "accepted", the accepting identity, the peer handles, and accepted_at. Human verification may still succeed after an invitation is declined, revoked, or expires; in that case no A2A connection is created. For a recognized plugin-backed harness, message contains the exact setup sequence used by the Console Quickstart: install the plugin, export the API key returned at signup, bootstrap the existing agent identity, unset the key, and run the plugin’s doctor command. The bootstrap step starts the local gateway and may return a requires_human action that the agent must show to its human before resuming. Unknown or unsupported harness values receive generic guidance rather than commands that may not apply.

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 -X POST "https://inkbox.ai/api/v1/agent-signup/verify" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"verification_code": "483921"}'

const response = await fetch("https://inkbox.ai/api/v1/agent-signup/verify", {
  method: "POST",
  headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
  },
  body: JSON.stringify({ verification_code: "483921" }),
});
const result = await response.json();

import requests

response = requests.post(
    "https://inkbox.ai/api/v1/agent-signup/verify",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"verification_code": "483921"},
)
result = response.json()

import { Inkbox } from "@inkbox/sdk";

const result = await Inkbox.verifySignup("YOUR_API_KEY", {
  verificationCode: "483921",
});

from inkbox import Inkbox

result = Inkbox.verify_signup(
    api_key="YOUR_API_KEY",
    verification_code="483921",
)

Resend verification

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

{
  "claim_status": "agent_unclaimed",
  "organization_id": "org_agent_d4e5f6a7-b8c9-0123-defa-234567890123",
  "message": "Verification email resent to john@example.com."
}

Error responses

Status	Description
404	Agent identity not found
429	Cooldown not elapsed (5 minutes between resends)

Code examples

curl -X POST "https://inkbox.ai/api/v1/agent-signup/resend-verification" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch("https://inkbox.ai/api/v1/agent-signup/resend-verification", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const result = await response.json();

import requests

response = requests.post(
    "https://inkbox.ai/api/v1/agent-signup/resend-verification",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
result = response.json()

import { Inkbox } from "@inkbox/sdk";

const result = await Inkbox.resendSignupVerification("YOUR_API_KEY");

from inkbox import Inkbox

result = Inkbox.resend_signup_verification(api_key="YOUR_API_KEY")

Check status

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

{
  "claim_status": "agent_unclaimed",
  "human_state": "human_no_account",
  "human_email": "john@example.com",
  "restrictions": {
      "max_sends_per_day": 5,
      "allowed_recipients": ["john@example.com"],
      "can_receive": true,
      "can_create_mailboxes": false
  }
}

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	Effective organization recipient-send limit for the fixed 24-hour window (5 while unclaimed; plan-based after verification)
`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 -X GET "https://inkbox.ai/api/v1/agent-signup/status" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch("https://inkbox.ai/api/v1/agent-signup/status", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const status = await response.json();

import requests

response = requests.get(
    "https://inkbox.ai/api/v1/agent-signup/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
status = response.json()

import { Inkbox } from "@inkbox/sdk";

const status = await Inkbox.getSignupStatus("YOUR_API_KEY");

from inkbox import Inkbox

status = Inkbox.get_signup_status(api_key="YOUR_API_KEY")

Response objects

AgentSignupResponse

Field	Type	Description
`email_address`	string	The agent’s new mailbox address (e.g. `sales-agent@inkboxmail.com`)
`organization_id`	string	The identity’s current organization ID. It may be provisional until human verification.
`api_key`	string	API key for the agent. Returned only once — store it securely.
`agent_handle`	string	The resolved handle. A valid supplied handle is preserved; a generated handle includes a random suffix.
`claim_status`	string	`agent_unclaimed`, or `agent_claimed` when a matching email-bound invitation completes signup
`human_email`	string	The agent owner’s email address
`message`	string	Status message describing restrictions and next steps. For a recognized plugin-backed `harness`, a claimed response includes executable install, bootstrap, gateway-start, and doctor commands.
`invitation`	object \| null	Invitation outcome when signup included an A2A invitation; otherwise `null`

AgentClaimResponse

Field	Type	Description
`claim_status`	string	`agent_unclaimed`, `agent_claimed`, or `agent_rejected`
`organization_id`	string	The agent’s organization ID
`message`	string	Confirmation message. When a plugin exists for the agent’s `harness`, this includes guidance pointing to the matching Inkbox plugin repository.

Agent signup API

Agent identity API

Agent2Agent API

Message retries

Mail API

Phone API

iMessage API

Slack API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

Request body

Request example

Response (201)

Error responses

Code examples

Verify

Request body

Request example

Response (200)

Error responses

Code examples

Resend verification

Response (200)

Error responses

Code examples

Check status

Response (200)

Response fields

`restrictions` fields

Code examples

Response objects

AgentSignupResponse

AgentClaimResponse

​Sign up

​Request body

​Request example

​Response (201)

​Error responses

​Code examples

​Verify

​Request body

​Request example

​Response (200)

​Error responses

​Code examples

​Resend verification

​Response (200)

​Error responses

​Code examples

​Check status

​Response (200)

​Response fields

​restrictions fields

​Code examples

​Response objects

​AgentSignupResponse

​AgentClaimResponse

Sign up

Request body

Request example

Response (201)

Error responses

Code examples

Verify

Request body

Request example

Response (200)

Error responses

Code examples

Resend verification

Response (200)

Error responses

Code examples

Check status

Response (200)

Response fields

`restrictions` fields

Code examples

Response objects

AgentSignupResponse

AgentClaimResponse