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.

---

# Register
description: Agent self-signup, verification, and status checking

---


# 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-Service-Token` header.

---

## Sign up `POST`


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
{
    "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."
}
```

### Response (201)

```json
{
    "email_address": "sales-agent-a1b2c3@inkboxmail.com",
    "organization_id": "org_agent_d4e5f6a7-b8c9-0123-defa-234567890123",
    "api_key": "isk_live_abc123...",
    "agent_handle": "sales-agent-a1b2c3",
    "claim_status": "agent_unclaimed",
    "human_email": "john@example.com",
    "message": "Agent registered. Verification email sent to john@example.com. Until verified, sending is limited to 10 emails/day to john@example.com only."
}
```

The `api_key` is returned only in this response. Store it immediately, because it cannot be retrieved again.

### Error responses

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

### Code examples

**cURL**

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

**JavaScript**

```javascript
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",
        display_name: "Sales Agent",
        note_to_human: "Hey John, please verify me!",
    }),
});
const result = await response.json();
// Store result.api_key securely — it won't be shown again
```

**Python**

```python
import requests

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

**Inkbox SDK (Python)**

```python
from inkbox import Inkbox

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

**Inkbox SDK (TypeScript)**

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

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

---

## Verify `POST`


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",
    "message": "Agent verified and claimed successfully."
}
```

### 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**

```bash
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"}'
```

**JavaScript**

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

**Python**

```python
import requests

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

**Inkbox SDK (Python)**

```python
from inkbox import Inkbox

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

**Inkbox SDK (TypeScript)**

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

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

---

## Resend verification `POST`


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**

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

**JavaScript**

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

**Python**

```python
import requests

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

**Inkbox SDK (Python)**

```python
from inkbox import Inkbox

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

**Inkbox SDK (TypeScript)**

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

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

---

## Check status `GET`


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": 10,
        "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 | 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**

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

**JavaScript**

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

**Python**

```python
import requests

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

**Inkbox SDK (Python)**

```python
from inkbox import Inkbox

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

**Inkbox SDK (TypeScript)**

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

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

---

## 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 |

### 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 |