# ThrowawayMail

> Free disposable email service. Create temporary mailboxes that expire in 10 minutes. No signup required.

ThrowawayMail provides anonymous temporary email addresses for testing, signups, and privacy. Mailboxes auto-expire after 10 minutes. All data is permanently deleted. The JSON API allows programmatic access for agents and automation.

## Quick Start

1. Create a mailbox: `POST /api/mailboxes`
2. Use the returned `address` to receive emails (e.g. `fuzzy-cloud-river@throwawaymail.app`)
3. Poll for messages: `GET /api/mailboxes/{mailbox_id}/messages`
4. Or subscribe to real-time notifications: `WS /api/ws/{mailbox_id}`
5. Read a message: `GET /api/mailboxes/{mailbox_id}/messages/{message_id}`
6. Optionally delete when done: `DELETE /api/mailboxes/{mailbox_id}`

The `mailbox_id` returned on creation is your only credential. Keep it to access the mailbox. Mailboxes auto-expire after 10 minutes.

## API Documentation

- [OpenAPI Spec](http://throwawaymail.app/api/docs): Interactive Swagger documentation for the JSON API
- [ReDoc](http://throwawaymail.app/api/redoc): Alternative API documentation
- [OpenAPI JSON](http://throwawaymail.app/api/openapi.json): Machine-readable OpenAPI 3.1 specification

## API Endpoints

### POST /api/mailboxes

Create a new temporary mailbox.

Request:

```
curl -X POST http://throwawaymail.app/api/mailboxes
```

Response (201 Created):

```json
{
  "mailbox_id": "01JABCDEF1234567890ABCDEF",
  "address": "fuzzy-cloud-river@throwawaymail.app",
  "expires_at": "2026-01-15T10:30:00Z",
  "created_at": "2026-01-15T10:20:00Z"
}
```

Fields:
- `mailbox_id` (string): Unique identifier for the mailbox. Use this in all subsequent API calls.
- `address` (string): The full email address to receive mail at.
- `expires_at` (string): ISO 8601 timestamp when the mailbox will be automatically deleted.
- `created_at` (string): ISO 8601 timestamp when the mailbox was created.

### GET /api/mailboxes/{mailbox_id}

Get mailbox details and a list of message summaries.

Request:

```
curl http://throwawaymail.app/api/mailboxes/01JABCDEF1234567890ABCDEF
```

Response (200 OK):

```json
{
  "mailbox_id": "01JABCDEF1234567890ABCDEF",
  "address": "fuzzy-cloud-river@throwawaymail.app",
  "expires_at": "2026-01-15T10:30:00Z",
  "created_at": "2026-01-15T10:20:00Z",
  "message_count": 1,
  "messages": [
    {
      "message_id": "01JXYZ9876543210XYZXYZXY",
      "from_address": "sender@example.com",
      "from_name": "Sender Name",
      "subject": "Welcome to our service",
      "received_at": "2026-01-15T10:22:00Z",
      "size": 1234,
      "read": false
    }
  ]
}
```

Response (404 Not Found):

```json
{
  "error": "Mailbox not found",
  "detail": null
}
```

### GET /api/mailboxes/{mailbox_id}/messages

List all messages in a mailbox.

Request:

```
curl http://throwawaymail.app/api/mailboxes/01JABCDEF1234567890ABCDEF/messages
```

Response (200 OK):

```json
[
  {
    "message_id": "01JXYZ9876543210XYZXYZXY",
    "from_address": "sender@example.com",
    "from_name": "Sender Name",
    "subject": "Welcome to our service",
    "received_at": "2026-01-15T10:22:00Z",
    "size": 1234,
    "read": false
  }
]
```

Message summary fields:
- `message_id` (string): Unique identifier for the message.
- `from_address` (string): Sender email address.
- `from_name` (string or null): Sender display name, if available.
- `subject` (string): Email subject line.
- `received_at` (string): ISO 8601 timestamp when the message was received.
- `size` (integer): Message size in bytes.
- `read` (boolean): Whether the message has been read.

### GET /api/mailboxes/{mailbox_id}/messages/{message_id}

Read a specific message with full content.

Request:

```
curl http://throwawaymail.app/api/mailboxes/01JABCDEF1234567890ABCDEF/messages/01JXYZ9876543210XYZXYZXY
```

Response (200 OK):

```json
{
  "message_id": "01JXYZ9876543210XYZXYZXY",
  "from_address": "sender@example.com",
  "from_name": "Sender Name",
  "subject": "Welcome to our service",
  "received_at": "2026-01-15T10:22:00Z",
  "size": 1234,
  "read": false,
  "to_addresses": ["fuzzy-cloud-river@throwawaymail.app"],
  "cc_addresses": null,
  "bcc_addresses": null,
  "reply_to": null,
  "text": "Welcome to our service! Your account is ready.",
  "html": "<p>Welcome to our service! Your account is ready.</p>"
}
```

Additional fields beyond the summary:
- `to_addresses` (list of strings): Recipient email addresses.
- `cc_addresses` (list of strings or null): CC recipient addresses.
- `bcc_addresses` (list of strings or null): BCC recipient addresses.
- `reply_to` (string or null): Reply-to address.
- `text` (string or null): Plain text body of the email.
- `html` (string or null): HTML body of the email.

### DELETE /api/mailboxes/{mailbox_id}

Delete a mailbox and all its messages immediately.

Request:

```
curl -X DELETE http://throwawaymail.app/api/mailboxes/01JABCDEF1234567890ABCDEF
```

Response: 204 No Content (empty body)

### WS /api/ws/{mailbox_id}

Subscribe to real-time new-mail notifications via WebSocket.

Connect:

```
wscat -c ws://throwawaymail.app/api/ws/01JABCDEF1234567890ABCDEF
```

When a new email arrives, the server sends:

```json
{"event": "new_mail"}
```

The connection closes with code 4004 if the mailbox does not exist.

## Agent Workflow Example

A typical agent workflow for receiving a verification email:

```bash
# 1. Create a temporary mailbox
RESPONSE=$(curl -s -X POST http://throwawaymail.app/api/mailboxes)
MAILBOX_ID=$(echo $RESPONSE | jq -r '.mailbox_id')
ADDRESS=$(echo $RESPONSE | jq -r '.address')

# 2. Use the address for signup (e.g. register on a website)
# ... use $ADDRESS wherever an email is needed ...

# 3. Poll for messages (or use WebSocket for real-time)
MESSAGES=$(curl -s http://throwawaymail.app/api/mailboxes/$MAILBOX_ID/messages)

# 4. Read the first message
MESSAGE_ID=$(echo $MESSAGES | jq -r '.[0].message_id')
MESSAGE=$(curl -s http://throwawaymail.app/api/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID)
echo $MESSAGE | jq '.text'

# 5. Clean up
curl -s -X DELETE http://throwawaymail.app/api/mailboxes/$MAILBOX_ID
```

## Rate Limits and Constraints

- No authentication required
- No rate limiting
- Mailboxes expire automatically after 10 minutes
- All data is permanently deleted on expiry
- Email domain: `throwawaymail.app`

## Optional

- [How It Works](http://throwawaymail.app/how-it-works): Explanation of the service
- [Privacy Policy](http://throwawaymail.app/privacy): Privacy policy