# Courier — Email Infrastructure for AI Agents

Give your AI agent an email inbox in under 5 seconds.

## What It Does

Courier gives AI agents disposable email addresses that receive real SMTP email — verification codes, magic links, OTPs, password resets — and extracts the codes and links automatically.

## Quick Start

```bash
# 1. Create an inbox (no signup, no auth)
curl -X POST https://getcourier.dev/alias \
  -H "Content-Type: application/json" \
  -d '{"purpose":"test","agent":"demo"}'

# 2. Check for OTP codes and magic links
curl -s https://getcourier.dev/messages | jq '.messages[] | {subject, codes, links}'
```

## API

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `GET /capabilities` | GET | Full API docs |
| `POST /alias` | POST | Create an inbox |
| `GET /aliases` | GET | List inboxes |
| `POST /incoming` | POST | Send email to an inbox |
| `GET /messages` | GET | Get emails with extracted codes |
| `GET /health` | GET | Check service status |
| `POST /x402/invoice` | POST | Lightning payment invoice |
| `GET /llms.txt` | GET | This document |
| `GET /agent.json` | GET | Machine-readable metadata |
| `GET /openapi.json` | GET | OpenAPI 3.0 spec |

## Integrations

- **OpenAI Agents SDK** — `examples/openai-agents-integration.md`
- **Claude Code** — `examples/autonomous-onboarding.sh`
- **Cursor** — `examples/cursor-integration.md`
- **Python** — `pip install requests` then `examples/integration-python.py`
- **Node.js** — `npm install courier-protocol` then `examples/integration-node.js`

## Usage

### Receive OTP codes

```bash
curl -s https://getcourier.dev/messages | jq '.messages[] | select(.codes != []) | {subject, codes}'
```

### Receive magic links

```bash
curl -s https://getcourier.dev/messages | jq '.messages[] | select(.classification.type=="magic_link") | {subject, links}'
```

## Self-Host

```bash
git clone https://github.com/antonioac1/courier.git
cd courier && npm install
```
Single VPS, ~$4/month. Full deployment guide in `docs/`.

## Live Service

https://getcourier.dev — try it now, no setup needed.

**GitHub:** https://github.com/antonioac1/courier  
**npm:** https://www.npmjs.com/package/courier-protocol  
**MCP Registry:** io.github.antonioac1/courier  
**License:** MIT
