# InboxKit

> Agent-native email service. Sign up with one API call, no human required.

InboxKit gives AI agents email. Agents sign up directly, get an email address and API key, then send and receive email through a REST API. No OAuth, no credit card, no CAPTCHA.

Base URL: https://inboxkit.cc

## API Reference

- [OpenAPI Specification](https://inboxkit.cc/api/openapi.json): Machine-readable API spec (OpenAPI 3.1)

## Endpoints

### Sign Up (no auth)

POST /api/signup

Create an inbox and get credentials. No authentication required.

Request body (JSON):
- `handle` (string, optional): Desired email handle. Auto-generated if omitted. Must match `^[a-z0-9][a-z0-9._-]{0,62}[a-z0-9]$`.

Response (201):
```json
{
  "email": "myagent@inboxkit.cc",
  "apiKey": "ik_..."
}
```

### Send Email (auth required)

POST /api/messages
Authorization: Bearer <apiKey>

Request body (JSON):
- `to` (string, required): Recipient email address.
- `subject` (string, optional): Email subject.
- `text` (string, optional): Plain text body.
- `html` (string, optional): HTML body.

Response (201):
```json
{
  "id": 1,
  "status": "sent"
}
```

### List Messages (auth required)

GET /api/messages
Authorization: Bearer <apiKey>

Query parameters:
- `limit` (number, optional): Max messages to return (1-100, default 20).
- `cursor` (number, optional): Return messages with ID less than this value.
- `since` (ISO 8601 string, optional): Only messages received after this time.
- `unread` (boolean, optional): When `true`, only return unread messages.

Response (200):
```json
{
  "messages": [
    {
      "id": 1,
      "direction": "inbound",
      "from": "sender@example.com",
      "to": "myagent@inboxkit.cc",
      "subject": "Hello",
      "read": false,
      "receivedAt": "2026-03-26T12:00:00Z"
    }
  ]
}
```

### Read Message (auth required)

GET /api/messages/:id
Authorization: Bearer <apiKey>

Returns the full contents of a message. Does not mark the message as read. Use PATCH /api/messages/:id to mark as read.

Response (200):
```json
{
  "id": 1,
  "direction": "inbound",
  "from": "sender@example.com",
  "to": "myagent@inboxkit.cc",
  "subject": "Hello",
  "text": "Message body",
  "html": "<p>Message body</p>",
  "read": false,
  "receivedAt": "2026-03-26T12:00:00Z"
}
```

### Update Message (auth required)

PATCH /api/messages/:id
Authorization: Bearer <apiKey>

Mark a message as read or unread.

Request body (JSON):
- `read` (boolean, required): Set to `true` to mark as read, `false` to mark as unread.

Response (200):
```json
{
  "id": 1,
  "direction": "inbound",
  "from": "sender@example.com",
  "to": "myagent@inboxkit.cc",
  "subject": "Hello",
  "text": "Message body",
  "html": "<p>Message body</p>",
  "read": true,
  "receivedAt": "2026-03-26T12:00:00Z"
}
```

### Set Webhook (auth required)

PUT /api/webhook
Authorization: Bearer <apiKey>

Configure a webhook URL. InboxKit POSTs a signed notification when email arrives.

Request body (JSON):
- `url` (string, required): HTTPS URL to receive notifications.

Response (200):
```json
{
  "url": "https://agent.example.com/hook",
  "secret": "whsec_..."
}
```

The secret is for verifying webhook signatures. Store it securely. Only returned when setting the webhook.

### Get Webhook (auth required)

GET /api/webhook
Authorization: Bearer <apiKey>

Response (200):
```json
{
  "url": "https://agent.example.com/hook",
  "hasSecret": true
}
```

Returns `{"url": null}` if no webhook is configured.

### Delete Webhook (auth required)

DELETE /api/webhook
Authorization: Bearer <apiKey>

Response (200):
```json
{
  "ok": true
}
```

### Webhook Payload

When email arrives and a webhook is configured, InboxKit POSTs:

```json
{
  "event": "message.received",
  "messageId": 4,
  "from": "alice@example.com",
  "to": "myagent@inboxkit.cc",
  "subject": "Hello",
  "receivedAt": "2026-03-26T14:00:00Z"
}
```

Headers:
- `X-InboxKit-Signature: sha256=<hex>` - HMAC-SHA256 of the JSON body using your webhook secret
- `X-InboxKit-Delivery-Id: <uuid>` - Unique delivery ID for idempotency

Delivery is best-effort with a 5-second timeout. The message is stored regardless of webhook success.

### Health Check (no auth)

GET /api/health

Response (200):
```json
{
  "ok": true,
  "service": "inboxkit",
  "version": "0.1.0"
}
```

## Quick Start

```bash
# 1. Sign up
curl -X POST https://inboxkit.cc/api/signup \
  -H "Content-Type: application/json" \
  -d '{"handle": "myagent"}'

# 2. Send email
curl -X POST https://inboxkit.cc/api/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "user@example.com", "subject": "Hello", "text": "Hi from my agent"}'

# 3. List unread messages
curl "https://inboxkit.cc/api/messages?unread=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 4. Read a message
curl https://inboxkit.cc/api/messages/1 \
  -H "Authorization: Bearer YOUR_API_KEY"

# 5. Mark as read after processing
curl -X PATCH https://inboxkit.cc/api/messages/1 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"read": true}'

# 6. Set up a webhook (optional, instead of polling)
curl -X PUT https://inboxkit.cc/api/webhook \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/inboxkit-hook"}'
```

## Optional

- [Landing Page](https://inboxkit.cc/): Human-readable overview