# DESTROY.NETWORK - Full Documentation for AI Assistants
> Comprehensive guide to the disposable email service, API, SDK, and CLI

## Overview
DESTROY.NETWORK provides instant, disposable email addresses. No signup, no personal data collection, automatic expiration.

---

## CLI Tool: dna

### Installation
```
# npm (recommended - pre-built binaries, no Go needed)
npm install -g @buun_group/dna

# Supported: Linux x64/arm64, macOS x64/arm64, Windows x64
```

### Authentication
API key resolution order:
1. `--api-key` flag
2. `DESTROY_API_KEY` environment variable
3. `~/.config/dna/config.json` (via `dna auth login`)

API keys start with `sk_live_` and require Pro plan or higher.

### Commands

#### Identity Management
```
dna create [--ttl 60] [--label "signup"] [--prefix bot] [--password-length 24] [--persona] [--no-persona] [--country US] [--gender female]
dna list                    # alias: dna ls
dna get <id>
dna extend <id> [--ttl 120] [--label "new"]
dna delete <id>             # alias: dna rm
```

#### Email Operations
```
dna messages <id>
dna message <id> <msg-id> [--html]
dna wait <id> [--timeout 60]
```

#### Verification Code Extraction
```
dna verify <id>                              # check existing emails
dna verify <id> --timeout 30                 # wait up to 30s
dna verify <id> --pattern "code:\s*(\d{6})"  # custom regex
```

Supports 13+ built-in patterns: 6-digit codes, 4-8 digit OTPs, alphanumeric codes, verification links, magic links, and more.

#### Vault Management
```
dna vault list [--category dev-tools] [--search github]
dna vault get <id>                                        # decrypt and show password + persona
dna vault get <id> --json | jq -r '.password'             # extract password for scripting
dna vault save <identity-id> --site "GitHub" [--url "https://github.com"] [--category dev-tools]
dna vault save --site "GitHub" --email bot@748392.best --password "Kx9#mL2p" [--category dev-tools] [--notes "CI account"]
dna vault delete <id>
```

#### Authentication Management
```
dna auth login    # interactive, saves to config
dna auth status   # check current auth
dna auth logout   # remove saved credentials
```

#### Configuration
```
dna config list                          # view all settings
dna config get <key>                     # get a single value
dna config set defaults.persona true     # always generate persona on create
dna config set defaults.country US       # default country code
dna config set defaults.gender female    # default gender
dna config unset defaults.country        # remove a default
```

Config stored at `~/.config/dna/config.json`. Env overrides: `DESTROY_DEFAULT_PERSONA`, `DESTROY_DEFAULT_COUNTRY`, `DESTROY_DEFAULT_GENDER`.

### Global Flags
- `--json` - JSON output for scripting
- `--quiet` / `-q` - Minimal output (IDs/values only)
- `--no-color` - Disable colored output
- `--api-key` - Override API key
- `--api-url` - Override API base URL

### Example: Automated Signup Flow
```bash
ID=$(dna create --ttl 30 --label "signup" --json | jq -r '.id')
EMAIL=$(dna get "$ID" --json | jq -r '.email')
PASSWORD=$(dna get "$ID" --json | jq -r '.password')

# ... use $EMAIL and $PASSWORD to sign up ...

CODE=$(dna verify "$ID" --timeout 30 --quiet)
# ... submit $CODE to verify account ...

dna delete "$ID"
```

---

## API Reference

### Authentication
Free tier: No authentication required for basic inbox creation
Paid tier: API key in header `Authorization: Bearer <api_key>`

### Endpoints

#### Create Inbox
```
POST /api/inbox
Content-Type: application/json
Body: { "name": "my-inbox", "domain": "destroy.email" }

Response:
{
  "id": "inb_abc123",
  "address": "my-inbox@destroy.email",
  "expiresAt": "2026-02-27T12:30:00Z",
  "createdAt": "2026-02-27T12:00:00Z"
}
```

#### Get Inbox Details
```
GET /api/inbox/{inbox_id}

Response:
{
  "id": "inb_abc123",
  "address": "my-inbox@destroy.email",
  "emailCount": 5,
  "expiresAt": "2026-02-27T12:30:00Z"
}
```

#### List Messages
```
GET /api/inbox/{inbox_id}/messages

Response:
{
  "messages": [
    {
      "id": "msg_xyz",
      "from": "sender@example.com",
      "subject": "Welcome!",
      "snippet": "First 200 characters...",
      "receivedAt": "2026-02-27T12:15:00Z",
      "hasAttachments": false
    }
  ]
}
```

#### Get Message Content
```
GET /api/inbox/{inbox_id}/messages/{message_id}

Response:
{
  "id": "msg_xyz",
  "from": "sender@example.com",
  "to": "my-inbox@destroy.email",
  "subject": "Welcome!",
  "text": "Plain text content...",
  "html": "<html>...</html>",
  "attachments": [],
  "receivedAt": "2026-02-27T12:15:00Z"
}
```

#### Delete Inbox
```
DELETE /api/inbox/{inbox_id}

Response: { "success": true }
```

#### Share Inbox with Team (Business)
```
POST /api/inbox/{inbox_id}/share
Body: { "teamId": "team_abc" }
```

---

### Agent Identities (Pro+)

#### Create Identity
```
POST /api/agent/identities
Body: {
  "inboxId": "ibx_existing_id",  // Optional: attach to existing inbox instead of creating new
  "ttlMinutes": 30,              // Ignored when inboxId is provided
  "label": "signup",
  "prefix": "agent",             // Ignored when inboxId is provided
  "domain": "destroy.email",     // Ignored when inboxId is provided
  "passwordLength": 16,
  "persona": true,
  "country": "US",
  "gender": "female"
}
Response: {
  "id": "ai_abc123",
  "email": "agent7k4x@748392.best",
  "password": "Kx9#mL2pQr4!vB7w",
  "inboxId": "ibx_existing_id",
  "expiresAt": "2026-02-27T12:30:00Z",
  "persona": {
    "firstName": "Jessica",
    "lastName": "Martinez",
    "fullName": "Jessica Martinez",
    "gender": "female",
    "country": "US",
    "username": "jessica_martinez_91",
    "dateOfBirth": "1991-06-14",
    "address": { "street": "4721 Oak Street", "city": "Austin", "state": "TX", "zip": "78701", "formatted": "4721 Oak Street, Austin, TX 78701" },
    "phone": "+1 555-482-7365"
  }
}
inboxId: optional. Pass an existing inbox ID to attach the identity to it (inbox must be active, owned by you, and not already have an identity). When omitted, a new inbox is created.
Persona fields: optional. Pass "persona": true to generate fictional identity data.
Supported countries: US, UK, AU, CA, DE, FR, JP, BR, IN, ES, IT, NL, KR, MX, SE, PL, NZ.
When "persona" is not requested, the field is null.
```

#### List Identities
```
GET /api/agent/identities
```

#### Get Identity
```
GET /api/agent/identities/{id}
```

#### Extend Identity
```
PATCH /api/agent/identities/{id}
Body: { "ttlMinutes": 60, "label": "updated-label" }
```

#### Delete Identity
```
DELETE /api/agent/identities/{id}?keepInbox=true
```
Query params: keepInbox (boolean, optional) - When true, only the identity is deleted; inbox and messages remain. Default: false (deletes identity + inbox + messages).

#### Extract Verification Code
```
GET /api/agent/identities/{id}/verify?timeout=30&pattern=custom_regex
Response: {
  "found": true,
  "type": "code",
  "value": "847291",
  "confidence": 0.95,
  "from": "noreply@github.com",
  "subject": "Verify your email"
}
```

#### List Identity Messages
```
GET /api/agent/identities/{id}/messages
```

#### Get Identity Message
```
GET /api/agent/identities/{id}/messages/{messageId}
```

#### Wait for New Email
```
GET /api/agent/identities/{id}/wait?timeout=60
```

---

### Agent Vault (Pro+)

Persistently save agent identity credentials with encrypted storage. Search by site or category, pin favorites, bulk manage entries.

#### Save Credentials
```
POST /api/vault
Body: {
  "siteName": "GitHub",
  "siteUrl": "https://github.com",
  "email": "bot7k4x@748392.best",
  "password": "Kx9#mL2pQr4!vB7w",
  "persona": "{\"firstName\":\"Jessica\",\"lastName\":\"Martinez\"}",
  "category": "dev-tools",
  "notes": "Test account for CI",
  "sourceIdentityId": "ai_abc123"
}
Response: {
  "id": "vault_abc123",
  "siteName": "GitHub",
  "email": "bot7k4x@748392.best",
  "category": "dev-tools",
  "pinned": false,
  "createdAt": "2026-02-27T12:00:00Z",
  "updatedAt": "2026-02-27T12:00:00Z"
}
```
Passwords and persona data are encrypted at rest. Only the owning user can decrypt them.
Categories: social, shopping, dev-tools, testing, gaming, finance, news, entertainment, work, other.

#### Save Identity to Vault
```
POST /api/vault/from-identity/{identityId}
Body: {
  "siteName": "Gunspec",
  "siteUrl": "https://gunspec.io",
  "category": "dev-tools",
  "notes": "Automated signup"
}
Response: {
  "id": "vault_abc123",
  "email": "q8mehzh_@748392.best",
  "siteName": "Gunspec",
  "siteUrl": "https://gunspec.io",
  "category": "dev-tools",
  "sourceIdentityId": "ai_abc123",
  "pinned": false,
  "createdAt": "2026-02-27T12:00:00Z"
}
```
Saves an active agent identity directly to the vault. Automatically pulls the email, password, and persona from the identity and re-encrypts for vault storage. Equivalent to `dna vault save <identity-id>`.

#### List Vault Entries
```
GET /api/vault?search=github&category=dev-tools
Response: {
  "entries": [
    {
      "id": "vault_abc123",
      "siteName": "GitHub",
      "email": "bot7k4x@748392.best",
      "category": "dev-tools",
      "notes": "Test account for CI",
      "pinned": true,
      "createdAt": "2026-02-27T12:00:00Z",
      "updatedAt": "2026-02-27T12:00:00Z"
    }
  ],
  "limit": 50
}
```
Returns metadata only (no passwords). Use GET /api/vault/{id} to decrypt. Search across site names, emails, and notes. Pinned entries sort first.

#### Get Vault Entry (Decrypted)
```
GET /api/vault/{id}
Response: {
  "id": "vault_abc123",
  "siteName": "GitHub",
  "email": "bot7k4x@748392.best",
  "password": "Kx9#mL2pQr4!vB7w",
  "persona": { "firstName": "Jessica", "lastName": "Martinez" },
  "category": "dev-tools",
  "notes": "Test account for CI",
  "pinned": true,
  "createdAt": "2026-02-27T12:00:00Z",
  "updatedAt": "2026-02-27T12:00:00Z"
}
```
Decrypts password and persona data for the authenticated user.

#### Update Vault Entry
```
PATCH /api/vault/{id}
Body: { "siteName": "GitHub Enterprise", "category": "dev-tools", "notes": "Updated", "pinned": true }
Response: { "updated": true }
```

#### Delete Vault Entry
```
DELETE /api/vault/{id}
Response: { "deleted": true }
```

#### Bulk Delete
```
POST /api/vault/bulk-delete
Body: { "ids": ["vault_abc123", "vault_def456"] }
Response: { "deleted": 2 }
```

#### Bulk Update Category
```
POST /api/vault/bulk-update
Body: { "ids": ["vault_abc123", "vault_def456"], "category": "work" }
Response: { "updated": 2 }
```

Limits: Pro 50 entries, Business 500 entries. Entries persist across sessions and do not expire.

---

### Inbox Rules (Pro+)

#### Create Rule
```
POST /api/rules
Body: {
  "name": "Forward GitHub",
  "senderPattern": ".*@github\\.com",
  "subjectPattern": null,
  "action": "forward",
  "forwardTo": "me@gmail.com",
  "priority": 1
}
```

Actions: `forward` (route to external address), `label` (apply label), `delete` (discard before storage)
Patterns: regex match on sender address and/or subject line
Priority: lower numbers evaluated first, first match wins

#### List Rules
```
GET /api/rules
```

---

### Labels (Pro+)

#### Create Label
```
POST /api/labels
Body: { "name": "Receipts", "color": "#10b981" }
```

#### List Labels
```
GET /api/labels
```

---

### Webhooks (Pro+)

#### Register Webhook
```
POST /api/webhooks
Body: {
  "url": "https://your-app.com/webhook",
  "events": ["message.received"],
  "inboxId": "inb_abc123"
}
```

Events: `message.received`, `inbox.created`, `inbox.expired`
Includes signing secret for payload verification. Failed deliveries are retried.

---

### Teams (Business)

#### Create Team
```
POST /api/teams
Body: { "name": "QA Team" }
```

#### Invite Member
```
POST /api/teams/{id}/invite
Body: { "email": "alice@company.com", "role": "admin" }
```

Roles: `owner` (full control), `admin` (manage members/inboxes), `member` (view shared inboxes)
Limits: 5 teams per account, 25 members per team

#### Real-Time Collaboration
Shared inboxes use WebSocket connections via Cloudflare Durable Objects:
- Live presence indicators (who's viewing)
- Real-time message delivery to all connected members
- Read receipts per message with timestamps
- 7-day read receipt history retention

---

### Inbox Templates

#### Create Template
```
POST /api/inbox-templates
Body: {
  "name": "QA Template",
  "domain": "destroy.email",
  "forwardTo": "team@company.com",
  "webhookUrl": "https://hooks.slack.com/...",
  "isDefault": true
}
```

Limits: Free 3, Pro 10, Business 25 templates

---

## TypeScript SDK

```
npm install @buun_group/destroy-network-sdk
```

```typescript
import { DestroyNetwork } from '@buun_group/destroy-network-sdk';

const dn = new DestroyNetwork({ apiKey: 'sk_live_...' });

// Inboxes
const inbox = await dn.inboxes.create({ name: 'test', domain: 'destroy.email' });
const messages = await dn.messages.list(inbox.id);
await dn.inboxes.delete(inbox.id);

// Agent identities
const identity = await dn.agent.create({ ttlMinutes: 30, label: 'signup' });
const result = await dn.agent.verify(identity.id, { timeout: 30 });
await dn.agent.delete(identity.id);

// Agent vault
await dn.vault.create({ siteName: 'GitHub', email: identity.email, password: identity.password, category: 'dev-tools' });
const entries = await dn.vault.list({ search: 'github' });
const entry = await dn.vault.get(entries[0].id); // decrypts password + persona
await dn.vault.update(entries[0].id, { pinned: true, category: 'work' });
await dn.vault.bulkDelete(['vault_abc123', 'vault_def456']);
await dn.vault.delete(entries[0].id);

// Agent identity with persona (fictional name, address, phone, DOB)
const personaIdentity = await dn.agent.create({ ttlMinutes: 30, persona: true, country: 'US', gender: 'female' });
console.log(personaIdentity.persona.fullName, personaIdentity.persona.phone);

// Inbox rules
await dn.inboxRules.create({ name: 'Forward', senderPattern: '.*@github\\.com', action: 'forward', forwardTo: 'me@gmail.com' });

// Labels
const label = await dn.labels.create({ name: 'Receipts', color: '#10b981' });

// Webhooks
await dn.webhooks.create({ url: 'https://app.com/hook', events: ['message.received'] });

// Teams
const team = await dn.teams.create({ name: 'QA' });
await dn.teams.invite(team.id, { email: 'alice@co.com', role: 'admin' });
await dn.inboxes.share(inbox.id, { teamId: team.id });

// Templates
await dn.inboxTemplates.create({ name: 'Default', domain: 'destroy.email', isDefault: true });
```

### SDK Resources
- `dn.inboxes` - create, list, update, delete, share
- `dn.messages` - list, get, search
- `dn.agent` - create, list, get, delete, extend, verify, wait, messages
- `dn.vault` - create, list, get, update, delete, bulkDelete, bulkUpdate
- `dn.inboxRules` - create, list, update, delete
- `dn.labels` - create, list, update, delete
- `dn.webhooks` - create, list, update, delete
- `dn.teams` - create, list, invite, manage members
- `dn.inboxTemplates` - create, list, update, delete
- `dn.domains` - list available domains
- `dn.apiKeys` - create, list, revoke
- `dn.user` - account info, stats
- `dn.billing` - subscription management

---

## Pricing Tiers

### Anonymous (no signup)
- 1 active inbox at a time per IP
- 2 inboxes created per hour per IP
- 10-minute lifetime, 1 extension
- Random inbox names only
- No API access
- Sign up for a free account to get more

### Free (signed in)
- 3 concurrent inboxes, 10-minute lifetime, 1 extension
- 5 inboxes created per hour
- Random inbox names only
- 5 MB max attachment size
- Polling-based updates (60s interval)
- 3 inbox templates
- Cross-device inbox recovery
- No API access, no rules, no forwarding, no teams

### Pro ($5/month or $48/year)
- 10 concurrent inboxes, 30-minute lifetime, unlimited extensions
- Custom inbox names, choose email domain
- 25 MB max attachment size
- Real-time SSE delivery
- 100 API requests/minute, 5 API keys
- 10 inbox rules, 10 labels, 10 templates
- Email forwarding, webhooks, message search
- 5 inbox aliases per inbox
- 10 agent identities, 30s wait timeout, persona generation
- Agent vault (50 entries), AES-256-GCM encrypted

### Business ($15/month or $144/year)
- 50 concurrent inboxes, 60-minute lifetime, unlimited extensions
- Custom names + 45-day name reservation (25 reserved names)
- 50 MB max attachment size
- Real-time SSE + WebSocket delivery
- 1,000 API requests/minute, 10 API keys
- 50 inbox rules, 50 labels, 25 templates
- 5 teams, 25 members per team, shared inboxes
- Live presence indicators, read receipts
- 25 inbox aliases per inbox
- 50 agent identities, 120s wait timeout, persona generation
- Agent vault (500 entries), AES-256-GCM encrypted
- Priority support

---

## Blog
- Disposable Email API for Developers: https://destroy.network/blog/disposable-email-api-for-developers
- Inbox Rules and Email Automation: https://destroy.network/blog/inbox-rules-email-automation
- Team Shared Inboxes for QA: https://destroy.network/blog/team-shared-inboxes-for-qa
- AI Agent Identities: https://destroy.network/blog/ai-agent-identities
- What Is Disposable Email: https://destroy.network/blog/what-is-disposable-email
- Testing Email Flows with Playwright: https://destroy.network/blog/testing-email-flows-with-playwright
- Protecting Your Privacy: https://destroy.network/blog/protecting-your-privacy-with-disposable-email
- Browser Extensions: https://destroy.network/blog/introducing-browser-extensions

---

## Technical Details

- **Platform**: Cloudflare Workers (edge computing, 300+ data centers)
- **Database**: Cloudflare D1 (SQLite at edge)
- **Storage**: Cloudflare R2 for attachments
- **Sessions**: Cloudflare KV
- **Email Processing**: Cloudflare Email Workers + postal-mime parser
- **Real-time**: SSE (Pro+) and WebSocket via Durable Objects (Business)
- **CLI**: Go binary distributed via npm (cross-platform pre-built binaries)
- **SDK**: TypeScript with full type safety

---

## Agent Playbooks

Step-by-step guides for common dna CLI workflows.
Full playbooks page: https://destroy.network/docs/playbooks

### Playbook 1: Basic Signup Flow
```bash
#!/usr/bin/env bash
set -euo pipefail
IDENTITY=$(dna create --ttl 30 --label "signup" --json)
ID=$(echo "$IDENTITY" | jq -r '.id')
EMAIL=$(echo "$IDENTITY" | jq -r '.email')
PASSWORD=$(echo "$IDENTITY" | jq -r '.password')
# Use $EMAIL and $PASSWORD to sign up on target website
CODE=$(dna verify "$ID" --timeout 30 --quiet)
# Submit $CODE on the verification page
dna delete "$ID"
```

### Playbook 2: Full Signup with Persona
```bash
IDENTITY=$(dna create --persona --country US --gender female --ttl 30 --json)
ID=$(echo "$IDENTITY" | jq -r '.id')
EMAIL=$(echo "$IDENTITY" | jq -r '.email')
PASSWORD=$(echo "$IDENTITY" | jq -r '.password')
FIRST=$(echo "$IDENTITY" | jq -r '.persona.firstName')
LAST=$(echo "$IDENTITY" | jq -r '.persona.lastName')
PHONE=$(echo "$IDENTITY" | jq -r '.persona.phone')
DOB=$(echo "$IDENTITY" | jq -r '.persona.dateOfBirth')
STREET=$(echo "$IDENTITY" | jq -r '.persona.address.street')
CITY=$(echo "$IDENTITY" | jq -r '.persona.address.city')
STATE=$(echo "$IDENTITY" | jq -r '.persona.address.state')
ZIP=$(echo "$IDENTITY" | jq -r '.persona.address.zip')
# Fill form with all persona fields, verify, then clean up
CODE=$(dna verify "$ID" --timeout 30 --quiet)
dna delete "$ID"
```

### Playbook 3: Verification Patterns
```bash
# Basic extraction
CODE=$(dna verify "$ID" --timeout 30 --quiet)

# Custom regex
CODE=$(dna verify "$ID" --pattern "activation code: (\w+)" --quiet)

# Link extraction
RESULT=$(dna verify "$ID" --timeout 30 --json)
TYPE=$(echo "$RESULT" | jq -r '.type')
VALUE=$(echo "$RESULT" | jq -r '.value')

# Retry with backoff
for i in $(seq 1 3); do
  CODE=$(dna verify "$ID" --timeout 15 --quiet 2>/dev/null) && break
  sleep 2
done

# Raw email fallback
MSG_ID=$(dna messages "$ID" --json | jq -r '.[0].id')
dna message "$ID" "$MSG_ID" --html
```

### Playbook 4: Batch Identity Creation
```bash
COUNT=5
IDS=()
for i in $(seq 1 "$COUNT"); do
  ID=$(dna create --ttl 60 --label "batch-$i" --quiet)
  IDS+=("$ID")
done
# List batch identities
dna list --json | jq -r '.[] | select(.label | startswith("batch-")) | .id'
# Extend all
for ID in "${IDS[@]}"; do dna extend "$ID" --ttl 120; done
# Delete all
for ID in "${IDS[@]}"; do dna delete "$ID"; done
```

### Playbook 5: Country-Specific Personas
Supported countries: US, UK, AU, CA, DE, FR, JP, BR, IN, ES, IT, NL, KR, MX, SE, PL, NZ
- US: "4721 Oak Street, Austin, TX 78701", +1 555-482-7365, First Last
- UK: "14 Kensington Road, London W8 4EP", +44 7700 900123, First Last
- JP: "東京都渋谷区神南1-2-3", +81 90-1234-5678, Last First
- DE: "Hauptstraße 42, 10115 Berlin", +49 170 1234567, First Last
- BR: "Rua das Flores 123, São Paulo SP 01310-100", +55 11 91234-5678, First Last

### Playbook 6: Configure CLI Defaults
```bash
dna config set defaults.persona true
dna config set defaults.country US
dna config set defaults.gender female
dna config list
# Override per-command: --no-persona, --country JP
# Env vars: DESTROY_DEFAULT_PERSONA, DESTROY_DEFAULT_COUNTRY, DESTROY_DEFAULT_GENDER
```

---

## Related Links
- Main site: https://destroy.network
- API Docs: https://destroy.network/docs
- CLI Docs: https://destroy.network/docs/cli
- Playbooks: https://destroy.network/docs/playbooks
- Agent Docs: https://destroy.network/docs/agent
- Vault Docs: https://destroy.network/docs/vault
- SDK Docs: https://destroy.network/docs?view=sdk
- Blog: https://destroy.network/blog
- Pricing: https://destroy.network/pricing
- Changelog: https://destroy.network/changelog
- Extension: https://destroy.network/extension
- Status: https://status.destroy.network