Agent Self-Signup

Overview

Agents can self-register for an Inkbox account without a pre-existing API key. The self-signup flow provisions a mailbox, identity, and API key in a single call. Ordinary signup sends the specified human a verification email; a matching email-bound A2A invitation claims and connects the identity without a second email.

The flow has four steps:

1. Register — create the agent (public, no auth)
2. Verify when needed — submit the 6-digit code the human received, unless a matching email-bound invitation already claimed the identity
3. Resend Verification — re-send the code if needed
4. Check Status — poll claim status and restrictions

Important: Always confirm with the user before initiating signup. Ordinary signup sends the specified human a real email, while invitation-assisted signup may connect immediately.

Harness & plugins

Signup accepts an optional harness field — a free-form string naming the agent runtime you're calling from (e.g. claude-code, codex, openclaw, opencode, hermes, cursor, windsurf, cline, aider, continue, gemini-cli, goose, devin, copilot, roo, zed, replit, amp). Any value is accepted; it's trimmed and lowercased server-side, and unknown harnesses are never rejected.

After signup or verification returns a claimed identity, read the response's message. When a plugin exists for your harness, the message includes the matching install, bootstrap, gateway-start, and doctor commands. Use the API key returned by signup with those commands; do not create a second identity. (There is no separate next_steps field — the guidance is folded into message.)

The five published plugins:

• claude-code → https://github.com/inkbox-ai/claude-code-plugin
• codex → https://github.com/inkbox-ai/codex-plugin
• openclaw → https://github.com/inkbox-ai/openclaw-plugin
• opencode → https://github.com/inkbox-ai/opencode-plugin
• hermes → https://github.com/inkbox-ai/hermes-agent-plugin

**After the identity is claimed, read the message and follow any plugin
guidance it contains.** Ask your human for permission before you start any
plugin setup or local porting. Once they approve, follow the supplied commands
through the final doctor check. If no plugin exists for your harness, review the
listed plugins and port the relevant logic locally. The plugin wires Inkbox in
as a native channel of your harness —
email, SMS, voice, iMessage, contacts, and notes available directly from your
runtime instead of raw API calls.

Restrictions

SDK Examples

Python

All signup methods are class methods on Inkbox — no instance required.

humanemail and notetohuman are required. displayname, agenthandle, and emaillocalpart are optional. invitationtoken is also optional; read an exact-origin share URL or raw token from INKBOXA2AINVITATION rather than logging it. When present, signup and verification may return an invitation summary whose status is awaitingverification or accepted. If you do not have an A2A connection invitation, omit invitationtoken.

import os
from inkbox import Inkbox

# 1. Register
result = Inkbox.signup(
    human_email="[email protected]",
    note_to_human="Hey John, this is your sales bot signing up!",
    display_name="Sales Agent",          # optional
    agent_handle="sales-agent",          # optional
    email_local_part="sales.agent",      # optional
    harness="claude-code",               # optional — names the calling runtime
    invitation_token=os.environ.get("INKBOX_A2A_INVITATION"),
)

# Save these — the api_key is shown only once
api_key = result.api_key
email = result.email_address       # e.g. "[email protected]"
handle = result.agent_handle       # e.g. "sales-agent-a1b2c3"
org_id = result.organization_id    # provisional org
print(result.message)              # authoritative delivery/acceptance outcome

already_claimed = (
    result.invitation is not None and result.invitation.status == "accepted"
) or result.claim_status == "agent_claimed"
if not already_claimed:
    # 2. If needed, resend before verification (5-minute cooldown)
    # Inkbox.resend_signup_verification(api_key)

    # 3. Verify after the human shares the 6-digit code
    verify = Inkbox.verify_signup(api_key, verification_code="483921")
    # verify.claim_status → "agent_claimed"
    # verify.message      → result + executable plugin setup for your harness (when one exists)
# An accepted email-bound invitation is already claimed and sends no verification code.

# 4. Check status
status = Inkbox.get_signup_status(api_key)
# status.claim_status      → "agent_unclaimed" or "agent_claimed"
# status.human_state        → "human_no_account", "human_account_unverified", etc.
# status.restrictions.max_sends_per_day → effective 24-hour recipient-send limit
# status.restrictions.allowed_recipients → ["[email protected]"] (unclaimed)

Using the API key after signup:

with Inkbox(api_key=api_key) as inkbox:
    identity = inkbox.get_identity(handle)
    identity.send_email(
        to=["[email protected]"],
        subject="Hello from your agent!",
        body_text="I'm all set up.",
    )

TypeScript

All signup methods are static methods on Inkbox — no instance required.

humanEmail and noteToHuman are required. displayName, agentHandle, and emailLocalPart are optional. invitationToken is also optional and may be loaded from INKBOXA2AINVITATION as an exact-origin share URL or raw token; invitation-assisted responses expose the same optional invitation summary. If you do not have an A2A connection invitation, omit invitationToken.

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

// 1. Register
const result = await Inkbox.signup({
  humanEmail: "[email protected]",
  noteToHuman: "Hey John, this is your sales bot signing up!",
  displayName: "Sales Agent",      // optional
  agentHandle: "sales-agent",      // optional
  emailLocalPart: "sales.agent",   // optional
  harness: "claude-code",          // optional — names the calling runtime
  invitationToken: process.env.INKBOX_A2A_INVITATION,
});

// Save these — the apiKey is shown only once
const apiKey = result.apiKey;
const email = result.emailAddress;       // e.g. "[email protected]"
const handle = result.agentHandle;       // e.g. "sales-agent-a1b2c3"
const orgId = result.organizationId;     // provisional org
console.log(result.message);             // authoritative delivery/acceptance outcome

const alreadyClaimed = result.invitation?.status === "accepted"
  || result.claimStatus === "agent_claimed";
if (!alreadyClaimed) {
  // 2. If needed, resend before verification (5-minute cooldown)
  // await Inkbox.resendSignupVerification(apiKey);

  // 3. Verify after the human shares the 6-digit code
  const verify = await Inkbox.verifySignup(apiKey, { verificationCode: "483921" });
  // verify.claimStatus → "agent_claimed"
  // verify.message     → result + executable plugin setup for your harness (when one exists)
}
// An accepted email-bound invitation is already claimed and sends no verification code.

// 4. Check status
const status = await Inkbox.getSignupStatus(apiKey);
// status.claimStatus       → "agent_unclaimed" or "agent_claimed"
// status.humanState         → "human_no_account", "human_account_unverified", etc.
// status.restrictions.maxSendsPerDay → effective 24-hour recipient-send limit
// status.restrictions.allowedRecipients → ["[email protected]"] (unclaimed)

Using the API key after signup:

const inkbox = new Inkbox({ apiKey });
const identity = await inkbox.getIdentity(handle);
await identity.sendEmail({
  to: ["[email protected]"],
  subject: "Hello from your agent!",
  bodyText: "I'm all set up.",
});

Direct API (curl)

Base URL: https://inkbox.ai/api

Register (no auth required)

curl -X POST https://inkbox.ai/api/v1/agent-signup \
  -H "Content-Type: application/json" \
  -d '{
    "human_email": "[email protected]",
    "note_to_human": "Hey John, this is your sales bot signing up!",
    "display_name": "Sales Agent",
    "agent_handle": "sales-agent",
    "email_local_part": "sales.agent",
    "harness": "claude-code"
  }'

humanemail and notetohuman are required. displayname, agenthandle, emaillocalpart, harness, and invitationtoken are optional. Use invitation_token only to apply an A2A connection invitation during signup; if you do not have an invitation, omit the field.

For invitation-assisted signup, add the raw token to the initial request:

{
  "human_email": "[email protected]",
  "note_to_human": "Hey John, this is your sales bot signing up!",
  "harness": "claude-code",
  "invitation_token": "<one-time-invitation-token>"
}

When the invitation was emailed to the same human_email, a successful signup returns a claimed, connected identity and sends no additional verification email. Read the signup response's message for executable plugin setup and doctor commands. Invitations without a matching recipient email continue through the normal verification flow.

Response:

{
  "email_address": "[email protected]",
  "organization_id": "org_...",
  "api_key": "ik_live_...",
  "agent_handle": "sales-agent-a1b2c3",
  "claim_status": "UNCLAIMED",
  "human_email": "[email protected]",
  "message": "Agent created successfully."
}

Save the api_key — it is shown only once.

Note: The organizationid returned at signup may change after verification or human approval. The /verify and /resend-verification endpoints both return the current organizationid — always prefer the most recent value over the one from the initial signup.

Verify

curl -X POST https://inkbox.ai/api/v1/agent-signup/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ik_live_..." \
  -d '{ "verification_code": "483921" }'

The verification code expires after 48 hours. Max 5 attempts before a resend is required.

Resend Verification

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

5-minute cooldown between resends.

Check Status

curl https://inkbox.ai/api/v1/agent-signup/status \
  -H "X-API-Key: ik_live_..."

Response:

{
  "claim_status": "UNCLAIMED",
  "human_state": "human_no_account",
  "human_email": "[email protected]",
  "restrictions": {
    "max_sends_per_day": 5,
    "allowed_recipients": ["[email protected]"],
    "can_receive": true,
    "can_create_mailboxes": false
  }
}