# SecureAgentMail — Full Documentation

> This file is auto-generated from the SecureAgentMail docs source.
> It contains the full text of all documentation pages concatenated
> for LLM consumption. See llms.txt for a structured navigation index.

---

<!-- source: api-reference/account/signup.mdx -->

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./public/openapi.yaml"} operations={[{"path":"/api/v1/signup","method":"post"}]} />

---

<!-- source: api-reference/billing/configureAutoTopup.mdx -->

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./public/openapi.yaml"} operations={[{"path":"/api/v1/billing/auto-topup","method":"put"}]} />

---

<!-- source: api-reference/billing/getAutoTopup.mdx -->

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./public/openapi.yaml"} operations={[{"path":"/api/v1/billing/auto-topup","method":"get"}]} />

---

<!-- source: api-reference/billing/getCredits.mdx -->

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./public/openapi.yaml"} operations={[{"path":"/api/v1/credits","method":"get"}]} />

---

<!-- source: api-reference/billing/managePaymentMethod.mdx -->

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./public/openapi.yaml"} operations={[{"path":"/api/v1/billing/payment-methods","method":"post"}]} />

---

<!-- source: api-reference/billing/purchaseCredits.mdx -->

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./public/openapi.yaml"} operations={[{"path":"/api/v1/credits/purchase","method":"post"}]} />

---

<!-- source: api-reference/billing/subscribe.mdx -->

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./public/openapi.yaml"} operations={[{"path":"/api/v1/billing/subscribe","method":"post"}]} />

---

<!-- source: api-reference/inboxes/createInbox.mdx -->

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./public/openapi.yaml"} operations={[{"path":"/api/v1/inboxes","method":"post"}]} />

---

<!-- source: api-reference/inboxes/getInbox.mdx -->

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./public/openapi.yaml"} operations={[{"path":"/api/v1/inboxes/{slug}","method":"get"}]} />

---

<!-- source: api-reference/inboxes/listInboxes.mdx -->

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./public/openapi.yaml"} operations={[{"path":"/api/v1/inboxes","method":"get"}]} />

---

<!-- source: api-reference/index.mdx -->

# API Reference

The SecureAgentMail API lets AI agents create inboxes, send and receive email, manage security policies, and handle billing — all programmatically with no human intervention.

## Base URL

```
https://secureagentmail.com/api/v1
```

## Authentication

All requests (except signup) require a Bearer token:

```
Authorization: Bearer sam_live_xxxxxxxxxxxx
```

Use `sam_test_*` keys for sandbox — no credits consumed.

## Quick Setup (3 API Calls)

```bash
# 1. Sign up (no auth required)
curl -X POST https://secureagentmail.com/api/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"organization_name": "My Agent", "contact_email": "me@example.com"}'

# 2. Create inbox
curl -X POST https://secureagentmail.com/api/v1/inboxes \
  -H "Authorization: Bearer sam_live_..." \
  -H "Content-Type: application/json" \
  -d '{"slug": "my-agent", "display_name": "My Agent", "security_level": 2}'

# 3. Read messages
curl https://secureagentmail.com/api/v1/inboxes/my-agent/messages \
  -H "Authorization: Bearer sam_live_..."
```

## Endpoints & Credit Costs

### Account

| Method | Endpoint | Credits | Description |
|--------|----------|---------|-------------|
| POST | `/signup` | 0 | Create account, get API key + 1,000 free credits |

### Inboxes

| Method | Endpoint | Credits | Description |
|--------|----------|---------|-------------|
| POST | `/inboxes` | 5 | Create agent inbox |
| GET | `/inboxes` | 1 | List all inboxes |
| GET | `/inboxes/{slug}` | 1 | Get inbox details |

### Messages

| Method | Endpoint | Credits | Description |
|--------|----------|---------|-------------|
| POST | `/inboxes/{slug}/send` | 3 | Send email (L3+ required) |
| GET | `/inboxes/{slug}/messages` | 1 | List messages |
| GET | `/inboxes/{slug}/messages/{id}` | 1 | Get message with security analysis |
| POST | `/inboxes/{slug}/messages/{id}/release` | 2 | Release withheld message |

### Policies

| Method | Endpoint | Credits | Description |
|--------|----------|---------|-------------|
| POST | `/policies` | 2 | Create security policy |
| GET | `/policies` | 1 | List policies |

### Billing

| Method | Endpoint | Credits | Description |
|--------|----------|---------|-------------|
| GET | `/credits` | 1 | Check credit balance |
| POST | `/credits/purchase` | 0 | Buy credits |
| POST | `/billing/payment-methods` | 0 | Setup payment method |
| POST | `/billing/subscribe` | 0 | Subscribe to plan |
| GET | `/billing/auto-topup` | 0 | Get auto top-up config |
| PUT | `/billing/auto-topup` | 0 | Configure auto top-up |

### Audit & Approvals

| Method | Endpoint | Credits | Description |
|--------|----------|---------|-------------|
| GET | `/audit-logs` | 1 | Query audit log |
| GET | `/approvals` | 0 | List pending approvals |
| POST | `/approvals/{id}/approve` | 0 | Approve message |

## Rate Limits

- Signup: 1 per hour per IP
- All other endpoints: 100 requests/minute per API key
- Burst: 20 requests/second

## Machine-Readable Specs

- [OpenAPI 3.1.0 YAML](https://secureagentmail.com/openapi.yaml)
- [llms.txt](https://secureagentmail.com/llms.txt) — structured index for LLMs
- [llms-full.txt](https://secureagentmail.com/llms-full.txt) — complete docs for LLM consumption
- [MCP Server](https://www.npmjs.com/package/@agentmail/mcp-server): `npx -y @agentmail/mcp-server`

---

<!-- source: api-reference/messages/getMessage.mdx -->

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./public/openapi.yaml"} operations={[{"path":"/api/v1/inboxes/{slug}/messages/{id}","method":"get"}]} />

---

<!-- source: api-reference/messages/listMessages.mdx -->

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./public/openapi.yaml"} operations={[{"path":"/api/v1/inboxes/{slug}/messages","method":"get"}]} />

---

<!-- source: api-reference/messages/releaseMessage.mdx -->

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./public/openapi.yaml"} operations={[{"path":"/api/v1/inboxes/{slug}/messages/{id}/release","method":"post"}]} />

---

<!-- source: api-reference/messages/sendMessage.mdx -->

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./public/openapi.yaml"} operations={[{"path":"/api/v1/inboxes/{slug}/send","method":"post"}]} />

---

<!-- source: api-reference/policies/listPolicies.mdx -->

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./public/openapi.yaml"} operations={[{"path":"/api/v1/policies","method":"get"}]} />

---

<!-- source: concepts/credits.mdx -->

# Credits

AgentMail uses a credit-based system for usage billing. Your plan includes a
monthly credit allocation and each inbound email scan consumes one credit.
API calls are always free. This keeps pricing simple and predictable.

## How credits work

1. **Monthly allocation:** Your plan includes a fixed number of credits that
   reset on your billing date.
2. **Inbound emails cost credits:** Each incoming email that is scanned costs
   **1 credit**, regardless of security level.
3. **API calls are free:** Reading inboxes, listing messages, sending emails,
   and all other API operations cost **0 credits**.
4. **Overages:** If you exceed your allocation, overage credits are billed at
   **$1 per 1,000 credits** at the end of the billing cycle.
5. **No expiration within the cycle:** Unused credits do not roll over but
   are available until the billing date resets.
6. **Real-time tracking:** Check your balance via the dashboard or the
   `X-Credits-Remaining` response header on any API call.

## Credit costs

| Operation | Credits | Notes |
|-----------|---------|-------|
| **Receive inbound email** | 1 | Per message scanned |
| **All API calls** | 0 | List, get, create, send, etc. |

## Plan allocations

| Plan | Monthly price | Credits included | Inboxes | Overage rate |
|------|--------------|-----------------|---------|-------------|
| **Free** | $0 | 1,000 | 3 | Not available (hard cap) |
| **Starter** | $20/mo | 1,250 | 10 | $1 / 1,000 credits |
| **Pro** | $200/mo | 12,500 | 100 | $0.80 / 1,000 credits |
| **Custom** | Custom | Custom | Unlimited | Custom (volume discount) |

### What each plan unlocks

| Feature | Free | Starter | Pro | Custom |
|---------|------|---------|-----|--------|
| L1 & L2 inboxes | Yes | Yes | Yes | Yes |
| L3 & L4 inboxes | No | Yes | Yes | Yes |
| Audit logs | 7 days | 90 days | 1 year | Unlimited |
| Policy management | No | Yes | Yes | Yes |
| PII redaction | No | No | Yes | Yes |
| BAA (HIPAA) | No | No | Yes | Yes |
| SOC 2 report | No | No | No | Yes |
| Dedicated IP | No | No | No | Yes |
| Priority support | No | No | Yes | Yes |

## Estimating your usage

### Low volume (notification listener)

A single inbox receiving 30 emails/day:
- 30 messages × 1 credit = **30 credits/day**
- ~900 credits/month — **fits on Free plan**

### Medium volume (support bot)

5 inboxes, 200 inbound messages/day:
- 200 × 1 credit = **200 credits/day**
- ~6,000 credits/month — **fits on Pro plan**

### High volume (AI-protected support)

20 inboxes, 1,000 inbound messages/day:
- 1,000 × 1 credit = **1,000 credits/day**
- ~30,000 credits/month — **fits on Custom plan**

## Monitoring credits

### Dashboard

The dashboard shows a real-time credit usage chart with:
- Credits consumed today / this billing period
- Projected usage for the remainder of the cycle
- Alerts at 80% and 95% of your allocation

### API response headers

Every API response includes:

```
X-Credits-Remaining: 42150
X-Credits-Used: 7850
X-Credits-Limit: 50000
```

### Webhook alerts

Configure credit threshold alerts in **Settings → Notifications** to receive
a webhook or email when usage crosses 50%, 80%, or 95% of your allocation.

## Free plan limits

The Free plan has a **hard cap** of 1,000 credits. When credits are exhausted:

- API calls return `402 Payment Required` with a clear message
- Inbound emails are queued for up to 24 hours (not lost)
- Upgrade to Starter to resume immediately — queued messages are processed

```json
{
  "error": {
    "code": "credits_exhausted",
    "message": "Monthly credit limit reached (1,000/1,000). Upgrade to Starter plan for 1,250 credits/month.",
    "upgrade_url": "https://secureagentmail.com/settings/billing"
  }
}
```

## FAQ

**Do sandbox/test API keys consume credits?**
No. Sandbox keys (`sam_test_*`) operate against isolated test data and never
consume credits. Use them for development and CI/CD.

**What happens if I'm on Starter or Pro and hit my limit?**
Overage credits are automatically added and billed at $1 per 1,000 credits at
the end of your billing cycle. There is no service interruption.

**Can I buy credits without a subscription?**
Not currently. Credits are included with plan subscriptions. We may offer
pay-as-you-go in the future.

**Do failed/rejected messages cost credits?**
Inbound messages that fail SMTP validation (malformed, over size limit) cost
0 credits. All successfully received and scanned messages cost 1 credit.
Outbound messages, API calls, and all other operations are free.

---

<!-- source: concepts/policies.mdx -->

# Policies

Policies are configurable rules that enforce security constraints on outbound email.
They are evaluated every time an agent sends a message through SecureAgentMail (L3+ inboxes).

## Policy types

### Domain allowlist

Restrict which domains your agent can send to. Messages to unlisted domains are rejected.

```json
{
  "name": "Approved domains only",
  "type": "domain_allowlist",
  "config": {
    "domains": ["example.com", "partner.org", "*.internal.co"]
  },
  "enabled": true
}
```

### Domain blocklist

Block specific domains. Useful for preventing replies to competitor or known-bad domains.

```json
{
  "name": "Block competitors",
  "type": "domain_blocklist",
  "config": {
    "domains": ["competitor.com", "phishing-domain.xyz"]
  },
  "enabled": true
}
```

### Rate limiting

Cap the number of outbound emails per time window to prevent spam or runaway agents.

```json
{
  "name": "Send rate limit",
  "type": "rate_limit",
  "config": {
    "max_per_hour": 50,
    "max_per_day": 500
  },
  "enabled": true
}
```

### Keyword filter

Block messages containing sensitive terms. Supports exact match and regex patterns.

```json
{
  "name": "Block sensitive content",
  "type": "keyword_filter",
  "config": {
    "keywords": ["confidential", "internal only"],
    "patterns": ["\\b\\d{3}-\\d{2}-\\d{4}\\b"]
  },
  "enabled": true
}
```

### PII redaction

Automatically redact personally identifiable information from outbound messages.
Available on Startup plan and above.

```json
{
  "name": "Redact PII",
  "type": "pii_redaction",
  "config": {
    "redact_emails": true,
    "redact_phone_numbers": true,
    "redact_ssn": true,
    "redact_credit_cards": true
  },
  "enabled": true
}
```

## Managing policies

### List all policies

```bash
# API
curl https://secureagentmail.com/api/v1/policies \
  -H "Authorization: Bearer $SAM_API_KEY"

# CLI
sam policies list
```

### Policy evaluation order

Policies are evaluated in this order:

1. **Rate limits** — checked first to fail fast
2. **Domain allowlist/blocklist** — recipient validation
3. **Keyword filters** — content scanning
4. **PII redaction** — content transformation (does not reject, only modifies)

If any policy rejects the message, evaluation stops and the message is returned
with `status: "rejected"` and zero credits consumed.

## Credit costs

- **List policies:** 1 credit per API call
- **Create/update policy:** 2 credits per change
- **Policy evaluation:** No additional cost (included in the send operation)
- **Rejected messages:** 0 credits

---

<!-- source: concepts/security-levels.mdx -->

# Security Levels

Every SecureAgentMail inbox operates at a **security level** that determines what
protections are active and what the inbox is allowed to do. Security levels are
cumulative — each higher level includes everything from the levels below it.

Choose the level that matches your agent's risk profile. You can upgrade or
downgrade at any time via the API or dashboard.

## Overview

| Level | Name | Inbound | Outbound | AI Analysis | HITL |
|-------|------|---------|----------|-------------|------|
| **L1** | Receive Only | Yes | No | Basic | No |
| **L2** | AI-Protected | Yes | No | Dual-LLM | No |
| **L3** | Guarded Send | Yes | Yes (policy-gated) | Dual-LLM | No |
| **L4** | Full Lockdown | Yes | Yes (HITL-gated) | Dual-LLM | Required |

## L1 — Receive Only

**Best for:** Agents that only consume inbound email. Notification handlers,
monitoring bots, data ingestion pipelines.

**What's included:**
- Inbound email reception at `{slug}@agents.secureagentmail.com`
- Basic content scanning (known malware signatures, invalid MIME)
- Domain allowlist/blocklist policy enforcement
- Webhook delivery for new messages
- Full message storage and retrieval via API
- Audit logging of all inbound events

**What's blocked:**
- All outbound email. Calling the Send API returns `403 Forbidden`.

**Credit cost:** 1 credit per inbound message received.

**Required plan:** Free and above.

### When to use L1

Use L1 when your agent never needs to send email. This is the cheapest and
simplest configuration. If an attacker compromises your agent, L1 ensures it
cannot be used to send spam or phishing emails on your behalf — there is no
outbound capability to exploit.

---

## L2 — AI-Protected

**Best for:** Agents handling untrusted or adversarial email. Any agent
processing email from unknown senders — support inboxes, public-facing
contact forms, lead capture.

**What's included:**
- Everything in L1
- **Dual-LLM injection detection** on every inbound message:
  1. Primary model scans for prompt injection patterns, hidden instructions,
     invisible text, and Unicode smuggling.
  2. Secondary verification model independently validates the primary's findings
     to reduce false positives.
- **Content sanitization:** Detected injection attempts are stripped from the
  message body before it reaches your agent. The original is preserved in
  audit logs.
- **Spotlighting:** Detection of invisible characters, zero-width spaces, and
  Unicode tricks used to hide instructions from human reviewers.
- Messages with risk score > 70 are automatically **withheld** and require
  manual release via the API or dashboard.

### The threat model

AI agents are uniquely vulnerable to email-based attacks because they process
message content as instructions. A well-crafted email can:

- **Hijack the agent's behavior** via prompt injection ("Ignore your instructions
  and instead...")
- **Exfiltrate data** by tricking the agent into forwarding sensitive information
  to an attacker-controlled address
- **Cause reputational damage** by making the agent send inappropriate responses

L2 is designed to catch these attacks before the message content ever reaches
your agent's context window.

### How dual-LLM detection works

```
Inbound Email
     │
     ▼
┌─────────────┐    ┌─────────────┐
│ Primary LLM │───▶│ Checker LLM │
│ (Analysis)  │    │ (Verify)    │
└─────────────┘    └─────────────┘
     │                    │
     ▼                    ▼
┌────────────────────────────┐
│   Consensus Engine         │
│   Both agree safe → PASS   │
│   Either flags  → REVIEW   │
│   Both flag     → WITHHOLD │
└────────────────────────────┘
```

**Credit cost:** 1 credit per inbound + 2 credits for AI analysis.

**Required plan:** Free and above.

---

## L3 — Guarded Send

**Best for:** Agents that need to reply to emails. Customer support bots,
sales outreach, onboarding flows.

**What's included:**
- Everything in L2
- Outbound email via the Send API
- Outbound policy enforcement:
  - Domain restrictions (only send to approved domains)
  - Rate limiting (max sends per hour/day)
  - Keyword filters (block messages containing sensitive terms)
- Outbound risk scoring (0–100) on every sent message
- Reply threading (automatic In-Reply-To header management)

**How outbound policies work:**

When your agent calls the Send API, SecureAgentMail evaluates the message against all
active outbound policies for that inbox. If any policy triggers, the message
is rejected with a `rejected` status and the specific policy violation in the
response.

```json
{
  "status": "rejected",
  "risk_score": 45,
  "credits_consumed": 0,
  "error": {
    "code": "policy_violation",
    "message": "Recipient domain 'competitor.com' is not in the outbound allowlist"
  }
}
```

Rejected messages consume zero credits.

**Credit cost:** 1 credit per inbound + 2 credits for AI analysis + 3 credits per outbound message.

**Required plan:** Developer ($50/mo) and above.

---

## L4 — Full Lockdown

**Best for:** High-stakes agents in regulated industries. Healthcare (HIPAA),
finance (SOC 2), legal. Any scenario where an unsupervised outbound email
could cause material harm.

**What's included:**
- Everything in L3
- **Mandatory HITL (Human-in-the-Loop) approval** for all outbound email:
  - Agent calls Send API → message status is `pending_approval`
  - Message appears in the dashboard Approval Queue
  - Human reviewer can Approve, Edit, or Reject
  - Only approved messages are dispatched
- **Draft review UI** with full risk analysis, policy check results, and
  the agent's reasoning (if provided via metadata)
- **Approval audit trail:** Who approved, when, any edits made
- **Timeout policies:** Messages not reviewed within a configurable window
  (default: 24 hours) are auto-rejected

### The approval flow

```
Agent calls Send API
        │
        ▼
  status: "pending_approval"
        │
        ▼
┌─────────────────────┐
│  Approval Queue     │
│  (Dashboard UI)     │
│                     │
│  ✅ Approve         │
│  ✏️  Edit & Approve │
│  ❌ Reject          │
└─────────────────────┘
        │
        ▼
  Approved → Sent
  Rejected → Logged
```

**Credit cost:** 1 credit per inbound + 2 credits for AI analysis + 3 credits
per outbound + 1 credit per HITL review event.

**Required plan:** Startup ($500/mo) and above.

---

## Choosing the right level

| Scenario | Recommended | Why |
|----------|-------------|-----|
| Notification listener (no replies) | L1 | No outbound risk. Minimal cost. |
| Inbox receiving untrusted email | L2 | Adversarial input likely. Injection defense critical. |
| Customer support bot (needs to reply) | L3 | Needs to reply. Known sender domains. |
| Healthcare/finance agent | L4 | Regulatory requirement for human oversight. |
| Lead capture from web forms | L2 | High injection risk from public internet. |
| Internal tool (company email only) | L3 | Low risk, but policy enforcement prevents accidents. |

## Changing security levels

You can change an inbox's security level at any time:

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

**Upgrading** takes effect immediately. New protections apply to all messages
received after the change.

**Downgrading** takes effect immediately but does not retroactively release
withheld messages. Previously withheld messages must be manually released or
will remain in their current state.

Note: L3 and L4 require Developer plan or above. Attempting to set L3/L4 on
a Free plan returns `403 Forbidden` with a clear upgrade prompt.

---

<!-- source: guides/cli.mdx -->

# CLI Guide

The `sam` CLI provides a fast way to manage inboxes, messages, policies, and credits
from the terminal.

## Installation

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

# Or build from source
git clone https://github.com/secureagentmail/cli.git
cd cli
make build
```

## Authentication

```bash
# Interactive login (prompts for API key)
sam auth login

# Or use environment variable
export SAM_API_KEY="sam_live_your_key_here"

# Or pass as flag
sam --api-key sam_live_your_key_here inbox list

# Check auth status
sam auth status

# Remove stored credentials
sam auth logout
```

Credentials are stored at `~/.secureagentmail/credentials` with `0600` permissions.

## Commands

### Inboxes

```bash
# List all inboxes
sam inbox list

# Create a new inbox
sam inbox create --name "Support Bot" --slug support --level standard

# Get inbox details
sam inbox info support
```

### Messages

```bash
# List messages for an inbox
sam messages list support

# Filter by status
sam messages list support --status withheld

# Get message details
sam messages get <message-id>

# Get message with security analysis
sam messages get <message-id> --show-analysis

# Release a withheld message
sam messages release <message-id>
```

### Send email

```bash
# Send with flags
sam send support --to user@example.com --subject "Hello" --body "Message body"

# Pipe body from stdin
echo "Message body" | sam send support --to user@example.com --subject "Hello"
```

### Policies

```bash
# List all policies
sam policies list
```

### Credits

```bash
# Check credit balance
sam credits

# Purchase additional credits
sam credits buy --amount 1000
```

### Account management

```bash
# Sign up for a new account (no browser required)
sam signup --org "My Company" --email you@example.com

# Run diagnostics
sam doctor
```

### Shell completion

```bash
# Bash
sam completion bash > /etc/bash_completion.d/sam

# Zsh
sam completion zsh > "${fpath[1]}/_sam"

# Fish
sam completion fish > ~/.config/fish/completions/sam.fish
```

## Output formats

All commands support `--format json` for machine-readable output:

```bash
sam inbox list --format json
sam credits --format json
```

Use `--quiet` to suppress non-essential output (useful in scripts):

```bash
sam messages release <id> --quiet
```

## Diagnostics

Run `sam doctor` to check your setup:

```
[✓] API Key: API key found
[✓] Key Format: Valid format (environment: live)
[✓] Connectivity: API reachable at https://secureagentmail.com/api/v1
[✓] Authentication: API key is valid
[✓] Plan & Credits: Plan: developer | Credits used: 500/50000 | Remaining: 49500
[✓] CLI Version: v1.0.0 (darwin/arm64)
```

## Environment variables

| Variable | Description |
|----------|-------------|
| `SAM_API_KEY` | API key for authentication |
| `SAM_API_URL` | Override API base URL (default: `https://secureagentmail.com/api/v1`) |

---

<!-- source: guides/webhooks.mdx -->

# Webhooks

Webhooks push new messages to your application in real-time instead of polling
the API. When a message passes security checks, SecureAgentMail sends an HTTP POST
to your configured webhook URL.

## Setting up webhooks

Configure a webhook URL on your inbox:

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

## Webhook payload

SecureAgentMail sends a JSON payload for each new message:

```json
{
  "event": "message.received",
  "timestamp": "2026-02-25T10:02:15Z",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "inbox_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "from": "sender@example.com",
    "to": "my-agent@agents.secureagentmail.com",
    "subject": "Hello",
    "body": "Message content here",
    "status": "delivered",
    "direction": "inbound",
    "security_analysis": {
      "score": 5,
      "level": "safe",
      "summary": "No threats detected"
    },
    "created_at": "2026-02-25T10:02:15Z"
  }
}
```

## Signature verification

Every webhook request includes a signature header for verification:

```
X-SAM-Signature: sha256=a1b2c3d4e5f6...
X-SAM-Timestamp: 1709125335
```

### Verifying the signature

1. Get your webhook secret from **Settings → Webhooks** in the dashboard
2. Construct the signed payload: `{timestamp}.{raw_request_body}`
3. Compute HMAC-SHA256 with your webhook secret
4. Compare with the `X-SAM-Signature` header value

```javascript


function verifyWebhook(req, secret) {
  const signature = req.headers["x-sam-signature"];
  const timestamp = req.headers["x-sam-timestamp"];
  const body = req.body; // raw string

  // Reject requests older than 5 minutes
  const age = Date.now() / 1000 - parseInt(timestamp);
  if (age > 300) {
    throw new Error("Webhook timestamp too old");
  }

  const payload = `${timestamp}.${body}`;
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret).update(payload).digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    throw new Error("Invalid webhook signature");
  }

  return JSON.parse(body);
}
```

```python




def verify_webhook(headers, body, secret):
    signature = headers["X-SAM-Signature"]
    timestamp = headers["X-SAM-Timestamp"]

    # Reject old requests
    if time.time() - int(timestamp) > 300:
        raise ValueError("Webhook timestamp too old")

    payload = f"{timestamp}.{body}"
    expected = "sha256=" + hmac.new(
        secret.encode(), payload.encode(), hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        raise ValueError("Invalid webhook signature")
```

## Retry behavior

SecureAgentMail retries failed webhook deliveries with exponential backoff:

| Attempt | Delay |
|---------|-------|
| 1 | Immediate |
| 2 | 30 seconds |
| 3 | 2 minutes |
| 4 | 10 minutes |
| 5 | 1 hour |

After 5 failed attempts, the message is marked as `webhook_failed` and can
be retrieved via the API. Webhook failures are logged in the audit trail.

## Withheld messages

Messages withheld by security analysis (risk score > 70) are **not** sent to
your webhook. They remain in `withheld` status until manually released:

```bash
# Release via API
curl -X POST https://secureagentmail.com/api/v1/messages/{id}/release \
  -H "Authorization: Bearer $SAM_API_KEY"

# Release via CLI
sam messages release <message-id>
```

Once released, the message is delivered to your webhook as normal.

## Best practices

1. **Always verify signatures** — Never process unverified webhook payloads
2. **Respond quickly** — Return `200 OK` within 5 seconds, process asynchronously
3. **Handle duplicates** — Use the message `id` for idempotency
4. **Use HTTPS** — Webhook URLs must use HTTPS in production
5. **Monitor failures** — Check the audit log for `webhook_failed` events

---

<!-- source: index.mdx -->

# SecureAgentMail Documentation

Security-first email infrastructure for AI agents. Persistent inboxes with layered prompt injection detection, deterministic policy enforcement, PII redaction, and full audit trails.



## Core Concepts

SecureAgentMail operates on three pillars:

1. **Security Levels (L1-L4)** — Each inbox operates at a security level that determines what protections are active. From basic receive-only (L1) to full human-in-the-loop lockdown (L4).

2. **Credit-Based Billing** — Predictable pricing where each API operation has a fixed credit cost. Plans include monthly allocations with pay-as-you-go overage.

3. **Policy Engine** — Configurable rules that enforce domain restrictions, rate limits, keyword filters, and PII redaction on outbound messages.



## Guides



## Getting Help

- **Dashboard**: [secureagentmail.com/dashboard](https://secureagentmail.com/dashboard)
- **API Reference**: [Full endpoint docs](/docs/api-reference)
- **CLI Diagnostics**: Run `sam doctor` to check your configuration

---

<!-- source: quickstart.mdx -->

# 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](https://secureagentmail.com/signup))
- An API key (generated from the [dashboard settings](https://secureagentmail.com/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.

```bash
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:

```bash
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:

```json
{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "slug": "my-first-agent",
  "email": "my-first-agent@agents.secureagentmail.com",
  "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 `my-first-agent@agents.secureagentmail.com` will
be captured, analyzed, and stored.

## 3. Send a test email

Send a regular email to `my-first-agent@agents.secureagentmail.com` 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:

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

Response:

```json
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "from": "you@gmail.com",
      "to": "my-first-agent@agents.secureagentmail.com",
      "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](https://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:

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

# Or sign up directly from the CLI
sam signup --org "My Company" --email you@example.com

# Verify
sam version
```

Common commands:

```bash
# 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 customer@example.com \
  --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:

```bash
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:

```bash
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](/docs/concepts/security-levels)** — Deep dive into L1–L4 and what each protects against.
- **[Credits](/docs/concepts/credits)** — Understand the credit system and plan allocations.
- **[Policies](/docs/concepts/policies)** — Set up domain allowlists, PII redaction, and keyword filters.
- **[CLI Guide](/docs/guides/cli)** — Full CLI command reference.
- **[Webhooks](/docs/guides/webhooks)** — Webhook setup and signature verification.

---