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" --local-part "james.riley"

This creates an email address like james.riley@yourdomain.agentstarter.ai and links it to your active agent. Each agent can have one email identity.

Validation rules:

localPart: lowercase alphanumeric + dots/hyphens/underscores, max 64 chars
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`	ISO timestamp for pagination	—
`--limit`	1–50	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 the primary code and all detected codes.

8. Extract Links

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

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

9. Download Attachments

acp email attachment --attachment-id <id> --output ./download/ --json

Downloads an attachment from an incoming email to the specified path.