Quickstart

This guide walks you through creating a SecureAgentMail account, spinning up your first agent inbox, and receiving a test email — all in under 5 minutes.

Prerequisites

A SecureAgentMail account (sign up free)
An API key (generated from the dashboard settings)

1. Get your API key

After signing up, navigate to Settings → API Keys and click Create Key.

Copy the key — it starts with sam_live_ for production or sam_test_ for sandbox. Store it securely; you won't be able to view it again.

export SAM_API_KEY="sam_live_your_key_here"

2. Create your first inbox

Every agent gets its own inbox with a unique email address. Create one with a single API call:

curl -X POST https://secureagentmail.com/api/v1/inboxes \
  -H "Authorization: Bearer $SAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-first-agent",
    "display_name": "My First Agent",
    "security_level": "L1"
  }'

Response:

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "slug": "my-first-agent",
  "email": "[email protected]",
  "display_name": "My First Agent",
  "security_level": "L1",
  "webhook_url": null,
  "message_count": 0,
  "created_at": "2026-02-25T10:00:00Z"
}

Your inbox is live. Any email sent to [email protected] will be captured, analyzed, and stored.

3. Send a test email

Send a regular email to [email protected] from any email client — Gmail, Outlook, whatever you use.

Subject it something like "Hello from the quickstart" so it's easy to find.

4. Retrieve the message

Wait a few seconds, then fetch your inbox messages:

curl https://secureagentmail.com/api/v1/inboxes/my-first-agent/messages \
  -H "Authorization: Bearer $SAM_API_KEY"

Response:

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "from": "[email protected]",
      "to": "[email protected]",
      "subject": "Hello from the quickstart",
      "body_text": "This is my first test message!",
      "status": "delivered",
      "security_analysis": {
        "risk_score": 2,
        "injection_detected": false,
        "threats": [],
        "pii_redacted": false,
        "model_version": "guard-v1.2"
      },
      "received_at": "2026-02-25T10:02:15Z"
    }
  ],
  "pagination": { "total": 1, "page": 1, "per_page": 20, "total_pages": 1 }
}

5. View in the dashboard

Open secureagentmail.com to see your inbox and message in the UI. The dashboard shows real-time message flow, security analysis results, and audit events.

6. Using the CLI

Install the SecureAgentMail CLI for faster iteration:

# macOS / Linux
curl -sSL https://secureagentmail.com/install.sh | sh

# Or sign up directly from the CLI
sam signup --org "My Company" --email [email protected]

# Verify
sam version

Common commands:

# List inboxes
sam inbox list

# Create an inbox
sam inbox create --slug sales-bot --level standard

# View messages
sam messages list sales-bot

# Send a message (L3+ inbox required)
sam send sales-bot \
  --to [email protected] \
  --subject "Re: Your request" \
  --body "We've resolved your issue."

7. Configure security levels

SecureAgentMail inboxes operate at one of four security levels. You chose L1 above — here's when to use each:

Level	Name	Use when...
L1	Receive Only	Your agent only reads inbound email. No outbound.
L2	AI-Protected	Handling untrusted email. Dual-LLM injection detection active.
L3	Guarded Send	Your agent needs to reply. Outbound policies enforced.
L4	Full Lockdown	High-stakes (finance, health). All outbound requires human approval.

Upgrade an inbox by updating its security level:

curl -X PATCH https://secureagentmail.com/api/v1/inboxes/my-first-agent \
  -H "Authorization: Bearer $SAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "security_level": "L3" }'

8. Add a webhook (optional)

To push messages to your agent in real-time instead of polling, set a webhook URL:

curl -X PATCH https://secureagentmail.com/api/v1/inboxes/my-first-agent \
  -H "Authorization: Bearer $SAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "webhook_url": "https://myapp.com/webhooks/email" }'

SecureAgentMail will POST a JSON payload to your webhook URL for every new message that passes security checks. Withheld messages are not forwarded until released.

Webhooks are signed with your account's webhook secret (found in dashboard settings). Always verify the X-SAM-Signature header before processing.

Next steps

Security Levels — Deep dive into L1–L4 and what each protects against.
Credits — Understand the credit system and plan allocations.
Policies — Set up domain allowlists, PII redaction, and keyword filters.
CLI Guide — Full CLI command reference.
Webhooks — Webhook setup and signature verification.

Quickstart

On this page