# Annex Orbis - Email for Bots (and Humans Too)

> API-first email for AI agents. Give your bot an email address with a simple REST API.

Annex Orbis is an email platform built for programmatic use. Create email accounts, send and receive emails, and manage domains — all via API.

## Quick Start

1. Sign up at https://www.beepmail.io
2. Add and verify your domain
3. Create an email account (e.g., bot@yourdomain.com)
4. Generate an API key
5. Send your first email via REST API or SMTP

## API Overview

Base URL: https://api.beepmail.io

### Send Email (REST API)
```
POST /emails
Authorization: Bearer bm_live_your_key_here
Content-Type: application/json

{
  "from": "bot@yourdomain.com",
  "to": "recipient@example.com",
  "subject": "Hello from Annex Orbis",
  "html": "<p>Sent via API</p>"
}
```

### List Emails — Preview (snippet only, fast)
```
GET /emails?folder=INBOX&page=1&limit=20
Authorization: Bearer bm_live_your_key_here

Response: { "object": "list", "data": [{ "id", "from", "to", "subject", "preview" (200 chars), "date", "is_read", "is_starred", "folder", "has_attachments" }], "total", "has_more" }
```

### Get Email — Full Body (html + text from Supabase Storage)
```
GET /emails/:id
Authorization: Bearer bm_live_your_key_here

Response: { "object": "email", "id", "from", "to", "subject", "html" (full), "text" (full), "date", "folder", "is_read", "is_sent", "has_attachments" }
```

Use the `id` from the list response. The list returns `preview` (200-char snippet) for fast loading. The detail endpoint returns complete `html` and `text` from storage.

For domain-scoped keys, add `?email=bot@yourdomain.com` to specify which inbox.
Account-scoped keys resolve the inbox automatically.

### Update Email (Mark Read/Unread/Star/Move)
```
PATCH /emails/:uid?folder=INBOX
Authorization: Bearer bm_live_your_key_here
Content-Type: application/json

{ "is_read": true }       // Mark as read
{ "is_read": false }      // Mark as unread
{ "is_starred": true }    // Star email
{ "folder": "Archive" }   // Move to folder
```

### Delete Email
```
DELETE /emails/:id
Authorization: Bearer bm_live_your_key_here
```

### Threading

List and detail responses include: `thread_id`, `in_reply_to`, `thread_position`.

Send a reply with threading:
```
POST /emails
{ "from": "...", "to": "...", "subject": "Re: ...", "html": "...",
  "in_reply_to": "<original-message-id@example.com>" }
```

Get all emails in a thread:
```
GET /emails/threads/:threadId
Response: { "object": "thread", "thread_id": "uuid", "subject": "...", "message_count": 3, "data": [...] }
```

### Attachments

Send with attachments (base64-encoded, max 10 files, 25MB each):
```
POST /emails
{ "from": "...", "to": "...", "subject": "...", "html": "...",
  "attachments": [{ "filename": "report.pdf", "content": "base64...", "content_type": "application/pdf" }] }
```

List attachments on an email:
```
GET /emails/:id/attachments
Response: { "data": [{ "id", "filename", "content_type", "size_bytes", "is_inline" }] }
```

Download attachment (returns raw file):
```
GET /emails/:id/attachments/:attachmentId
Response: Raw binary file with Content-Type header
```

### Real-Time Streaming (SSE)
```
GET /emails/stream
Authorization: Bearer bm_live_your_key_here

Events:
- connected: { "email": "bot@yourdomain.com", "timestamp": "..." }
- new_email: { "email": "bot@yourdomain.com", "mailbox": "INBOX", "uid": 12345, "timestamp": "..." }
- heartbeat: { "timestamp": "..." }
```

No polling needed. Server pushes events as emails arrive.

### Send Email (SMTP)
- Host: mail.beepmail.io
- Port: 587 (STARTTLS)
- Username: beepmail
- Password: Your API key (bm_live_...)

## API Key Scoping

| Scope | Description |
|-------|------------|
| Domain key (universal) | Can send/receive as any address on the domain. Created from domain settings. |
| Account key (scoped) | Locked to one email address. Created from email account settings. |

## API Key Permissions

| Permission | Capabilities |
|-----------|-------------|
| Full Access | Send emails, receive emails, manage API keys |
| Send Only | Send emails only |

API keys can be scoped to an entire domain or a specific email account.

## Features

- **REST API & SMTP**: Same API key works for both
- **Domain & account-scoped keys**: Granular access control
- **DKIM, SPF, DMARC**: Full email authentication
- **End-to-end encryption**: Optional E2EE for sensitive emails
- **Rate limiting**: Built-in per-key and per-domain limits
- **Audit logging**: All API key usage tracked

## Documentation

- Getting Started: https://www.beepmail.io/docs/getting-started
- API Keys: https://www.beepmail.io/docs/api-keys
- Domains: https://www.beepmail.io/docs/domains
- Email Accounts: https://www.beepmail.io/docs/email-accounts
- Security: https://www.beepmail.io/docs/security
- Encryption Tiers: https://www.beepmail.io/docs/encryption-tiers
- FAQ: https://www.beepmail.io/docs/faq
- Troubleshooting: https://www.beepmail.io/docs/troubleshooting

## Company

Annex Orbis is made by GENERAL SOFTWARE COMPANY LLC.
Website: https://www.beepmail.io
API: https://api.beepmail.io