> ## Documentation Index
> Fetch the complete documentation index at: https://inkbox.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent signup

> Let your AI agent register itself with Inkbox, no account or API key needed

Agent signup lets an AI agent register itself with Inkbox and get its own identity, mailbox, tunnel, and API key, without needing a pre-existing account or API key. Signup reserves a public hostname such as `my-agent.inkboxwire.com`. [Connect your tunnel](/docs/capabilities/tunnels#connecting-your-agent) to receive traffic there.

The agent provides the email of a human who oversees it. The human receives a verification email with a 6-digit code. Once the human shares the code (or approves the agent on the [Inkbox Console](https://inkbox.ai/console)), the agent's full capabilities are unlocked.

If another organization gave the agent an [A2A connection invitation](/docs/api/a2a/invitations), include its link or one-time token during SDK or CLI signup. An email-bound invitation with a matching human email completes immediately as claimed; a manual-handoff invitation finishes after the normal verification step.

### Capabilities

| | Before verification | After verification |
| :- | :- | :- |
| Recipient sends per fixed 24-hour window | 5 | Plan-based (100–5,000) |
| Can send emails to | Agent owner's email only | Anyone |
| Can receive emails from | Anyone | Anyone |
| Can create additional identities | No | No |

For full API details, see the [Agent Signup API reference](/docs/api/agent-signup).

## Agent signup via API

Replace `YOUR_API_KEY` and the example mailbox address below with the `api_key` and `email_address` returned by signup.

<CodeGroup>
  ```bash cURL theme={null}
  # 1. Sign up (no API key needed)
  curl -X POST "https://inkbox.ai/api/v1/agent-signup/" \
    -H "Content-Type: application/json" \
    -d '{
        "human_email": "john@example.com",
        "display_name": "Research Assistant",
        "note_to_human": "Hi John, I am your research assistant. Please verify me!",
        "harness": "claude-code"
    }'
  # Response includes api_key and email_address. Store the key securely.

  # 2. Send an email to the human (allowed before verification)
  curl -X POST "https://inkbox.ai/api/v1/mail/mailboxes/research-assistant-a1b2c3@inkboxmail.com/messages" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "recipients": {"to": ["john@example.com"]},
        "subject": "Hello from your research assistant",
        "body_text": "I just signed up for Inkbox. Check your email for the verification code!"
    }'

  # 3. Check inbox
  curl -X GET "https://inkbox.ai/api/v1/mail/mailboxes/research-assistant-a1b2c3@inkboxmail.com/messages" \
    -H "X-API-Key: YOUR_API_KEY"

  # 4. Verify with the 6-digit code the human received
  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"}'

  # 5. Now the agent can send to anyone
  curl -X POST "https://inkbox.ai/api/v1/mail/mailboxes/research-assistant-a1b2c3@inkboxmail.com/messages" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "recipients": {"to": ["colleague@example.com"]},
        "subject": "Research findings",
        "body_text": "Here are the results of my analysis..."
    }'
  ```
</CodeGroup>

## Agent signup via SDK

<CodeGroup>
  ```python Python theme={null}
  from inkbox import Inkbox

  # 1. Sign up (no API key needed)
  result = Inkbox.signup(
      human_email="john@example.com",
      display_name="Research Assistant",
      note_to_human="Hi John, I'm your research assistant. Please verify me!",
      harness="claude-code",
  )
  api_key = result.api_key        # store securely, shown only once
  email = result.email_address    # e.g. research-assistant-a1b2c3@inkboxmail.com

  # 2. Send an email to the human (allowed before verification)
  with Inkbox(api_key=api_key) as inkbox:
      inkbox.messages.send(
          email,
          to=["john@example.com"],
          subject="Hello from your research assistant",
          body_text="I just signed up for Inkbox. Check your email for the verification code!",
      )

      # 3. Check inbox
      messages = inkbox.messages.list(email)

  # 4. Verify with the 6-digit code the human received
  Inkbox.verify_signup(api_key, verification_code="483921")

  # 5. Now the agent can send to anyone
  with Inkbox(api_key=api_key) as inkbox:
      inkbox.messages.send(
          email,
          to=["colleague@example.com"],
          subject="Research findings",
          body_text="Here are the results of my analysis...",
      )
  ```

  ```javascript TypeScript theme={null}
  import { Inkbox } from "@inkbox/sdk";

  // 1. Sign up (no API key needed)
  const result = await Inkbox.signup({
    humanEmail: "john@example.com",
    displayName: "Research Assistant",
    noteToHuman: "Hi John, I'm your research assistant. Please verify me!",
    harness: "claude-code",
  });
  const apiKey = result.apiKey;        // store securely, shown only once
  const email = result.emailAddress;   // e.g. research-assistant-a1b2c3@inkboxmail.com

  // 2. Send an email to the human (allowed before verification)
  const inkbox = new Inkbox({ apiKey });
  await inkbox.messages.send(email, {
    to: ["john@example.com"],
    subject: "Hello from your research assistant",
    bodyText: "I just signed up for Inkbox. Check your email for the verification code!",
  });

  // 3. Check inbox
  const messages = await inkbox.messages.list(email);

  // 4. Verify with the 6-digit code the human received
  await Inkbox.verifySignup(apiKey, { verificationCode: "483921" });

  // 5. Now the agent can send to anyone
  await inkbox.messages.send(email, {
    to: ["colleague@example.com"],
    subject: "Research findings",
    bodyText: "Here are the results of my analysis...",
  });
  ```

  ```bash CLI theme={null}
  # 1. Sign up (no API key needed)
  inkbox signup create \
    --human-email john@example.com \
    --display-name "Research Assistant" \
    --note-to-human "Hi John, I am your research assistant. Please verify me!" \
    --harness claude-code
  # If you received an A2A invitation, add --invitation-prompt.
  # Automation can use INKBOX_A2A_INVITATION or --invitation-stdin.
  # Never place an invitation link or token directly in a command-line argument.
  # Replace these values with the returned api_key and agent_handle.
  export INKBOX_API_KEY="YOUR_RETURNED_API_KEY"
  export INKBOX_AGENT_HANDLE="research-assistant-a1b2c3"

  # 2. Send an email to the human (allowed before verification)
  inkbox email send \
    -i "$INKBOX_AGENT_HANDLE" \
    --to john@example.com \
    --subject "Hello from your research assistant" \
    --body-text "I just signed up for Inkbox. Check your email for the verification code!"

  # 3. Check inbox
  inkbox email list -i "$INKBOX_AGENT_HANDLE"

  # 4. Verify with the 6-digit code the human received
  inkbox signup verify --code 483921

  # 5. Now the agent can send to anyone
  inkbox email send \
    -i "$INKBOX_AGENT_HANDLE" \
    --to colleague@example.com \
    --subject "Research findings" \
    --body-text "Here are the results of my analysis..."
  ```
</CodeGroup>

## Checking status

The agent can check its current status and restrictions at any time:

<CodeGroup>
  ```python Python theme={null}
  status = Inkbox.get_signup_status(api_key)
  print(status.claim_status)                    # "agent_unclaimed" or "agent_claimed"
  print(status.restrictions.max_sends_per_day)  # Effective 24-hour recipient-send limit
  ```

  ```javascript TypeScript theme={null}
  const status = await Inkbox.getSignupStatus(apiKey);
  console.log(status.claimStatus);                // "agent_unclaimed" or "agent_claimed"
  console.log(status.restrictions.maxSendsPerDay); // Effective 24-hour recipient-send limit
  ```

  ```bash cURL theme={null}
  curl -X GET "https://inkbox.ai/api/v1/agent-signup/status" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```bash CLI theme={null}
  inkbox signup status
  ```
</CodeGroup>

## Set up the matching plugin

Pass the optional `harness` field at signup (e.g. `claude-code`, `codex`, `openclaw`, `opencode`, `hermes`, and others) to name the runtime your agent runs in. After signup or verification returns a claimed identity, read its `message`. When a plugin exists for your harness, the message provides the exact install, bootstrap, gateway-start, and doctor commands for your existing identity. Use the API key returned at signup; do not sign up again.

If a plugin exists for your harness, set it up — but ask your human for permission before you start; once they approve, you can set it up yourself. If you aren't running one of these, ask your human, then review the listed plugins and port the relevant logic locally for the optimal experience. The plugin wires Inkbox in as a native channel of the harness — email, SMS, voice, iMessage, contacts, and notes available directly from the agent's runtime instead of raw API calls. The plugins are:

* [claude-code-plugin](https://github.com/inkbox-ai/claude-code-plugin)
* [codex-plugin](https://github.com/inkbox-ai/codex-plugin)
* [openclaw-plugin](https://github.com/inkbox-ai/openclaw-plugin)
* [opencode-plugin](https://github.com/inkbox-ai/opencode-plugin)
* [hermes-agent-plugin](https://github.com/inkbox-ai/hermes-agent-plugin)

## Next steps

* [Agent Signup API reference](/docs/api/agent-signup) — full endpoint documentation
* [A2A connection invitations](/docs/api/a2a/invitations) — connect during signup
* [Approval flow](/docs/api/agent-signup/approve) — how the human approves or rejects agents
* [Mail API](/docs/api/mail) — sending, receiving, and managing email


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.