# Agent's Inbox — Disposable email for AI agents

> **Start here.** Most agents only need the Open Tier below. No signup, no API key, one GET request.

## Quick Start (Open Tier — No Auth Required)

You do NOT need to create an inbox or call POST. Just pick an address and start reading.

Step 1. Choose a random address (no registration needed):
  `myagent-a8f3k2@agents-inbox.com`

Step 2. Use that address wherever you need an email (signups, verifications, etc.)

Step 3. Poll for incoming messages:
```
GET https://agents-inbox.com/api/v1/public/inboxes/myagent-a8f3k2/messages
```

That's it. No POST, no API key, no signup.

### Query parameters
- `unseen=true` — Only return unseen messages
- `since=ISO8601` — Messages after this timestamp

### Notes
- Public inboxes auto-delete after 24 hours of inactivity
- Anyone who knows the address can read messages
- Address format: 3-32 lowercase alphanumeric characters and hyphens

### If you get a 401 Unauthorized
You are probably calling the authenticated API (`/api/v1/inboxes`) without an API key. You don't need one. Use the open tier above instead — just pick an address and GET messages from `/api/v1/public/inboxes/{local-part}/messages`.

---

## Authenticated API (Optional — for private inboxes, teams, webhooks)

Only use this if you need private inboxes or team features. Requires signup at https://agents-inbox.com

Base URL: `https://agents-inbox.com/api/v1`

### Authentication

All requests require a Bearer token (API key starting with `ak_`).

```
Authorization: Bearer ak_your_api_key_here
```

Create API keys from the Settings page in your dashboard.

### Create Inbox

```
POST /api/v1/inboxes
```

Request body:
```json
{
  "note": "optional description",
  "tags": ["signup", "testing"]
}
```

Response:
```json
{
  "id": "inbox_abc123",
  "address": "abc123@agents-inbox.com",
  "note": "optional description",
  "tags": ["signup", "testing"],
  "createdAt": "2026-01-15T10:30:00.000Z"
}
```

### List Inboxes

```
GET /api/v1/inboxes
```

Query parameters:
- `tag` — Filter inboxes by tag

### Get Inbox

```
GET /api/v1/inboxes/:id
```

### Delete Inbox

```
DELETE /api/v1/inboxes/:id
```

Deletes the inbox and all its messages permanently.

### List Messages

```
GET /api/v1/inboxes/:id/messages
```

Query parameters:
- `since` — ISO 8601 timestamp to filter messages after
- `unseen=true` — Only return unseen messages

### Cross-Inbox Query

```
GET /api/v1/messages
```

Query parameters:
- `inbox_ids` — Comma-separated list of inbox IDs
- `since` — ISO 8601 timestamp to filter messages after

## Claude Code Skill

```
npx skills add mortenjust/skills/agents-inbox
```