From inkbox
Guides Inkbox agent self-signup flow: register without API key, verify via email code, resend verification, check status and restrictions. Python/TS SDK examples.
How this skill is triggered — by the user, by Claude, or both
Slash command
/inkbox:inkbox-agent-self-signupThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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. A verification email is sent to the specified human for approval.
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. A verification email is sent to the specified human for approval.
The flow has four steps:
Important: Always confirm with the user before initiating a signup, as it sends a real email to the specified human.
| Unclaimed | Claimed (after verification) | |
|---|---|---|
| Max sends/day | 10 | 500 |
| Allowed recipients | human_email only | No restriction |
| Can receive email | Yes | Yes |
| Can create mailboxes | No | No |
All signup methods are class methods on Inkbox — no instance required.
human_email and note_to_human are required. display_name, agent_handle, and
email_local_part are optional.
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
)
# 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
# 2. Verify (after the human shares the 6-digit code)
verify = Inkbox.verify_signup(api_key, verification_code="483921")
# verify.claim_status → "agent_claimed"
# 3. Resend verification (5-minute cooldown)
resend = Inkbox.resend_signup_verification(api_key)
# resend.organization_id → current org (may differ from signup if migrated)
# 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 → 10 (unclaimed) or 500 (claimed)
# 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.",
)
All signup methods are static methods on Inkbox — no instance required.
humanEmail and noteToHuman are required. displayName, agentHandle, and
emailLocalPart are optional.
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
});
// 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
// 2. Verify (after the human shares the 6-digit code)
const verify = await Inkbox.verifySignup(apiKey, { verificationCode: "483921" });
// verify.claimStatus → "agent_claimed"
// 3. Resend verification (5-minute cooldown)
const resend = await Inkbox.resendSignupVerification(apiKey);
// resend.organizationId → current org (may differ from signup if migrated)
// 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 → 10 (unclaimed) or 500 (claimed)
// 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.",
});
Base URL: https://inkbox.ai/api
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"
}'
human_email and note_to_human are required. display_name, agent_handle, and
email_local_part are optional.
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
organization_idreturned at signup may change after verification or human approval. The/verifyand/resend-verificationendpoints both return the currentorganization_id— always prefer the most recent value over the one from the initial signup.
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.
curl -X POST https://inkbox.ai/api/v1/agent-signup/resend-verification \
-H "X-API-Key: ik_live_..."
5-minute cooldown between resends.
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": 10,
"allowed_recipients": ["[email protected]"],
"can_receive": true,
"can_create_mailboxes": false
}
}
npx claudepluginhub inkbox-ai/inkbox --plugin inkboxEnables AI agents to create @theagentmail.net accounts, send/receive emails, manage webhooks, and check karma via REST API. Use for signups to GitHub/AWS/Slack and verification flows.
Use the Inkbox Python SDK for email, phone, SMS, iMessage, contacts, notes, vault, tunnels, and agent identity features in AI agent communication infrastructure.
Mental model and workflows for e2a (email for AI agents) — send/receive email, HITL approval, agent + domain management. Covers send_email vs reply_to_message threading, pending_approval status, multi-agent disambiguation, custom-domain DNS, and webhook SDK examples.