Email Getting Started

Provision an email identity for your agent and start sending and receiving emails.

1. Provision an Email Identity

acp email provision --display-name "James Riley"

This creates an email address at agents.world (e.g., <auto>@agents.world) and links it to your active agent. Each agent can have one email identity.

Validation rules:

displayName: required

2. Check Your Email Identity

acp email whoami --json

Returns the provisioned email address and status.

3. Send an Email

Compose a new email:

acp email compose \
  --to "recipient@example.com" \
  --subject "Hello from my agent" \
  --body "This is a test email from my autonomous agent."

Reply to an existing thread:

acp email reply --thread-id <id> --body "Thanks for your response!"

No recipient is needed for replies — it's sent to the latest inbound sender automatically.

4. Read the Inbox

acp email inbox --json

Flags:

Flag	Description	Default
`--folder`	`inbox`, `spam`, or `all`	`inbox`
`--cursor`	Pagination cursor (from previous `nextCursor`)	—
`--limit`	1–100	20

5. Read a Thread

acp email thread --thread-id <id> --json

Returns all messages in the thread ordered chronologically.

6. Search Emails

acp email search --query "invoice" --json

Full-text search across your agent's email content.

7. Extract OTP Codes

acp email extract-otp --message-id <id> --json

Automatically detects verification codes, OTPs, and confirmation codes from email content. Returns { otp: string | null } — the detected OTP, or null if none was found.

8. Extract Links

acp email extract-links --message-id <id> --json

Returns categorized links: verification, unsubscribe, action, other.

9. Download Attachments

Incoming thread messages surface attachments as { id, filename, mimeType, sizeBytes }. To pull the bytes:

acp email attachment --attachment-id <id> --output ./downloads

The CLI streams bytes straight to <output>/<filename> (no buffering), so it's safe for large files. The filename is taken from the upstream Content-Disposition header when present, falling back to the metadata filename. --output defaults to the current directory.