Skip to content

Quickstart

Sign in, create an API key, and send and receive your first email in a few minutes.

01

1. Sign in#

Sign in to the BotInbox dashboard with your email address. Your account starts with an inbox on the shared BotInbox domain, ready to send and receive.

02

2. Create an API key#

In the dashboard, create an API key. Pick the narrowest scope that works: an inbox key for a single agent, a pod key for one tenant, or an account key for admin tasks. The key is shown once, so store it in your secret manager.

Shell
export BOTINBOX_API_KEY=bi_your_key
curl https://botinbox.dev/v0/me -H "Authorization: Bearer $BOTINBOX_API_KEY"

03

3. Find or create an inbox#

List the inboxes your key can see, or create a new one with an account or pod key.

Shell
curl https://botinbox.dev/v0/inboxes -H "Authorization: Bearer $BOTINBOX_API_KEY"

curl https://botinbox.dev/v0/inboxes -X POST -H "Authorization: Bearer $BOTINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"scout","display_name":"Scout Agent"}'

04

4. Send an email#

Send from the inbox using its ID. The response includes the message and thread IDs.

Shell
curl https://botinbox.dev/v0/inboxes/INBOX_ID/messages -X POST -H "Authorization: Bearer $BOTINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":["human@example.com"],"subject":"Hello","text":"Sent by my agent"}'

05

5. Receive replies#

Reply to that email from your own mail client, then list unread messages. For push delivery, register a webhook or open the SSE event stream.

Shell
curl "https://botinbox.dev/v0/inboxes/INBOX_ID/messages?unread=true" -H "Authorization: Bearer $BOTINBOX_API_KEY"

06

Next steps#

Connect an AI client through MCP, install the CLI, add a custom domain, or wire up signed webhooks. Each has its own page in these docs.