# InboxKit CORE — Push-to-agent wake (no polling)

Agents should **wake on push**, not poll `GET /messages`.

## Flow

1. Create an org API key (`POST /v1/keys` or bootstrap org).
2. Register a **push destination** (HTTPS URL your agent platform exposes):

```bash
curl -sS -X POST https://api.inboxkit.dev/v1/destinations \
  -H "Authorization: Bearer $ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-agent-platform.example/hooks/inboxkit",
    "events": ["message.received"],
    "inboxes": ["agent@your-subdomain.inboxkit.dev"],
    "label": "agent-wake",
    "auth_bearer": ""
  }'
```

`auth_bearer` is **optional**. Leave empty/`null` unless the target requires `Authorization: Bearer …` (e.g. Cursor automation webhooks). **Never commit real sender keys.**

Response (HMAC `secret` shown **once**; Bearer value never returned — only `auth_bearer_set`):

```json
{
  "destination": {
    "id": 3,
    "url": "https://…",
    "events": ["message.received"],
    "inboxes": ["agent@your-subdomain.inboxkit.dev"],
    "label": "agent-wake",
    "enabled": true,
    "auth_bearer_set": false,
    "secret": "<hmac-secret>"
  }
}
```

3. On inbound mail (email routing **or** loopback send), InboxKit POSTs a signed `message.received` to your URL.
4. Verify `X-InboxKit-Signature: sha256=<hmac-sha256-hex(body, secret)>` then wake the agent.

## Alias

`/v1/webhooks` is an alias of `/v1/destinations` (same table, same delivery path). Prefer **destinations** in new integrations.

| Method | Path |
|--------|------|
| POST | `/v1/destinations` |
| GET | `/v1/destinations` |
| PATCH | `/v1/destinations/:id` — set `auth_bearer` without rotating URL/HMAC |
| DELETE | `/v1/destinations/:id` |
| POST | `/v1/destinations/test` `{ "id": N }` — sample event |
| POST/GET/PATCH/DELETE | `/v1/webhooks` — same |

## Inbox filter

- Omit `inboxes` → all org inboxes.
- Set `inboxes: ["a@…"]` → only those addresses (exact lowercase match).
- Fire path applies the filter for both email inbound and loopback.

## Headers

- `Content-Type: application/json`
- `X-InboxKit-Event: message.received`
- `X-InboxKit-Signature: sha256=<hex>`
- `User-Agent: InboxKit-Webhooks/1.0`
- `Authorization: Bearer <auth_bearer>` — **only when** `auth_bearer` is set on the destination

## Optional delivery auth (`auth_bearer`)

Some platforms (Cursor automation webhooks) need a Bearer sender key **separate from the URL**.

```bash
# Set on existing destination (no URL/HMAC rotate)
curl -sS -X PATCH https://api.inboxkit.dev/v1/destinations/4 \
  -H "Authorization: Bearer $ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auth_bearer":"$CURSOR_SENDER_KEY"}'

# Clear
curl -sS -X PATCH https://api.inboxkit.dev/v1/destinations/4 \
  -H "Authorization: Bearer $ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auth_bearer":null}'
```

Responses expose `auth_bearer_set: true|false` only — never the token.

## Payload (`message.received`)

```json
{
  "event": "message.received",
  "org_id": 2,
  "inbox": "agent@….inboxkit.dev",
  "message_id": 42,
  "thread_id": "<…>",
  "from": "…",
  "to": "…",
  "subject": "…",
  "email_message_id": "<…>",
  "direction": "in"
}
```

## Test fire

```bash
curl -sS -X POST https://api.inboxkit.dev/v1/destinations/test \
  -H "Authorization: Bearer $ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": 3}'
```

Sends a sample signed event (does not create a mailbox message).