Inkbox

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

---

# Agent signup
description: Let your AI agent register itself with Inkbox, no account or service token needed

---


# Agent signup

Agent signup lets an AI agent register itself with Inkbox and get its own identity, mailbox, and API key, without needing a pre-existing account or service token.

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.

### Capabilities

| | Before verification | After verification |
| :--- | :--- | :--- |
| Max sends per day | 10 | 500 |
| Can send emails to | Agent owner's email only | Anyone |
| Can receive emails from | Anyone | Anyone |
| Can create mailboxes | No | No |

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

## Agent signup via API

**cURL**

```bash
# 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!"
    }'
# 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/mailboxes/research-assistant-a1b2c3@inkboxmail.com/messages" \\
    -H "X-Service-Token: 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/mailboxes/research-assistant-a1b2c3@inkboxmail.com/messages" \\
    -H "X-Service-Token: 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-Service-Token: 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/mailboxes/research-assistant-a1b2c3@inkboxmail.com/messages" \\
    -H "X-Service-Token: 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..."
    }'
```

## Agent signup via SDK

**Python**

```python
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!",
)
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.mail.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.mail.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.mail.messages.send(
        email,
        to=["colleague@example.com"],
        subject="Research findings",
        body_text="Here are the results of my analysis...",
    )
```

**TypeScript**

```javascript
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!",
});
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.mail.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.mail.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.mail.messages.send(email, {
    to: ["colleague@example.com"],
    subject: "Research findings",
    bodyText: "Here are the results of my analysis...",
});
```

**CLI**

```bash
# 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!"
# Output includes api_key and email_address. Store the key securely.

# 2. Send an email to the human (allowed before verification)
inkbox email send \\
    --from research-assistant-a1b2c3@inkboxmail.com \\
    --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 --mailbox research-assistant-a1b2c3@inkboxmail.com

# 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 \\
    --from research-assistant-a1b2c3@inkboxmail.com \\
    --to colleague@example.com \\
    --subject "Research findings" \\
    --body-text "Here are the results of my analysis..."
```

## Checking status

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

**Python**

```python
status = Inkbox.get_signup_status(api_key)
print(status.claim_status)                    # "agent_unclaimed" or "agent_claimed"
print(status.restrictions.max_sends_per_day)  # 10 or 500
```

**TypeScript**

```javascript
const status = await Inkbox.getSignupStatus(apiKey);
console.log(status.claimStatus);                // "agent_unclaimed" or "agent_claimed"
console.log(status.restrictions.maxSendsPerDay); // 10 or 500
```

**cURL**

```bash
curl -X GET "https://inkbox.ai/api/v1/agent-signup/status" \\
    -H "X-Service-Token: YOUR_API_KEY"
```

**CLI**

```bash
inkbox signup status
```

## Next steps

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