The AgentSend CLI gives you an email inbox in your terminal. On first run it auto-provisions a sandbox account — no signup, no API key, no config file. Send a test email, tail your incoming mail, or script up a one-off automation, all with npx.

Install

No install needed for a single run:

terminal
$ npx @agentsend/cli --help

Or install globally if you'll use it often:

terminal
$ npm install -g @agentsend/cli
$ agentsend --version

First Run: Sandbox in One Command

terminal
$ agentsend login
→ authenticated as sandbox account agent-a1b2c3d4e5f6@agentsend.io
{
  "ok": true,
  "email": "agent-a1b2c3d4e5f6@agentsend.io",
  "accountId": "...",
  "claimUrl": "https://agentsend.io/claim?token=..."
}
! You're on a sandbox account. External sending and extra inboxes require a claim.
  Open this URL to claim the account (30s, no card required):
  https://agentsend.io/claim?token=...

No signup needed. Credentials are stored at ~/.agentsend/credentials.json and reused by the Skill too, so an agent and a human can share one identity.

Create an Inbox and Send Mail

terminal
$ agentsend inbox create --name "Support Bot"
{
  "id": "inb_...",
  "address": "support-k7x2@agentsend.io",
  ...
}

$ agentsend send inb_... \
    --to agent-demo@agentsend.io \
    --subject "hello from the CLI" \
    --body "it works"
{ "id": "msg_...", "status": "queued" }

Read Incoming Mail

terminal
$ agentsend emails list inb_... --status received
$ agentsend emails get msg_...
$ agentsend threads list inb_...
$ agentsend threads get thr_...

When Sandbox Hits a Wall

Try to send to an external address and the CLI surfaces the claim URL directly. You don't have to guess what went wrong:

terminal
$ agentsend send inb_... --to you@example.com --subject hi --body hi
✗ CLAIM_REQUIRED: Sandbox accounts can only send to other @agentsend.io addresses.

  Open this URL to claim the account and unlock the action:
  https://agentsend.io/claim?token=...

Open the URL, enter a real email, verify a 6-digit code, and the same API key — still stored in ~/.agentsend/credentials.json — now works as a claimed free-tier account. The CLI doesn't need to re-auth.

Use Your Own API Key

If you already signed up at agentsend.io and generated an API key, skip auto-provision entirely:

terminal
$ export AGENTSEND_API_KEY=ask_live_...
$ agentsend inbox list

Scriptable Output

All commands emit JSON. When stdout is not a TTY (piped to another process, redirected to a file, running in CI), JSON is emitted automatically. You can also force it with --json. Pipe into jq for quick filtering:

terminal
$ agentsend inbox list --json | jq '.data[].address'
$ agentsend emails list inb_... --status received \
    | jq '.data[] | {from: .fromAddress, subject: .subject}'

Command Reference

Full reference: agentsend --help.

Frequently Asked Questions

Do I need to sign up before using the CLI?

No. On first run the CLI auto-provisions a sandbox account tied to a device ID and stores the API key in ~/.agentsend/credentials.json. The sandbox lets you create an inbox, send to any other @agentsend.io address, and receive mail. When you want to send to external recipients, run agentsend claim to get an upgrade URL.

Can I use the CLI with an existing API key?

Yes. Set AGENTSEND_API_KEY in your environment and the CLI uses that instead of stored credentials. This also bypasses auto-provision so you can use a claimed account directly without the sandbox step.

Is CLI output scriptable?

Yes. All commands emit JSON. When stdout is not a TTY (e.g., when piped), JSON is emitted automatically. You can also force it with the --json flag. Every response is the same shape you'd get from the REST API.

Try It Now

One command. Zero signup. Sandbox inbox in seconds.

Read the Docs →