Abateganya

# Shaka Client Mailbox API — AI skill

You are integrating the **Shaka Client Mailbox API (v1)**: server-to-server access to one organisation service mailbox. Use this as the source of truth for auth, endpoints, bodies, webhooks, and limits.

## Base URL

`https://mail.shaka.rw`

- API root: `https://mail.shaka.rw/api/v1`
- Health (no auth): `GET https://mail.shaka.rw/api/health`

Response `200`:

```json
{ "ok": true, "status": "healthy" }
```

If DB is down → `503` `{ "ok": false, "status": "unhealthy" }`.

## Critical constraints

- **Server-to-server only.** Browser CORS is not enabled — never call this API from frontend JS. Keep keys and webhook secrets on the backend.
- Keys are **organisation-scoped** and bound to **one service mailbox** on that org’s domain.
- Platform admins create keys under **Admin → Organisations → API keys**. The secret is shown **once** at creation (`dm_live_…` prefix).

## Authentication

```
Authorization: Bearer dm_live_YOUR_KEY
```

Scopes (grant as needed):

| Scope | Purpose |
|-------|---------|
| `send` | Send mail and reply |
| `read` | List, get, patch, delete messages; download attachments |
| `webhook` | Receive signed inbound webhooks (requires webhook URL + secret at key creation) |

Missing scope → `403` with `{ "error": "Missing scope: …", "code": "forbidden" }`.
Invalid/missing auth → `401` `{ "error": "Unauthorized", "code": "unauthorized" }`.

## Error shape

All API errors:

```json
{ "error": "human-readable message", "code": "snake_case_code" }
```

Common codes: `unauthorized`, `forbidden`, `invalid_request`, `invalid_subject`, `not_found`, `send_failed`, `send_unconfigured`, `unavailable`, `trash_failed`, `delete_failed`, `restore_failed`.

## Endpoints

### `GET /api/v1/me` — any scope

```bash
curl https://mail.shaka.rw/api/v1/me \
  -H "Authorization: Bearer dm_live_YOUR_KEY"
```

Response `200`:

```json
{
  "organization": {
    "id": "org_01h…",
    "domain": "yourdomain.com",
    "name": "Acme"
  },
  "mailbox": {
    "id": "mbx_01h…",
    "email": "noreply@yourdomain.com",
    "name": "Noreply"
  },
  "scopes": ["send", "read", "webhook"],
  "key": {
    "id": "key_01h…",
    "name": "Production",
    "prefix": "dm_live_abc"
  }
}
```

### `GET /api/v1/messages` — `read`

Query params:

| Param | Notes |
|-------|--------|
| `direction` | `inbound` \| `outbound` (optional) |
| `q` | Search string (optional) |
| `trash` | `1` for trash folder |
| `cursor` | Pagination cursor (previous page’s last `created_at`) |
| `limit` | 1–100, default 50 |

```bash
curl "https://mail.shaka.rw/api/v1/messages?direction=inbound&limit=50" \
  -H "Authorization: Bearer dm_live_YOUR_KEY"
```

Response `200` (list rows use snake_case; pagination cursor is camelCase `nextCursor`):

```json
{
  "messages": [
    {
      "id": "eml_01h…",
      "direction": "inbound",
      "from_addr": "customer@example.com",
      "to_addr": "noreply@yourdomain.com",
      "subject": "Hello",
      "is_read": false,
      "is_draft": false,
      "has_attachments": false,
      "has_replied": false,
      "created_at": "2026-08-03 12:00:00",
      "updated_at": null
    }
  ],
  "nextCursor": null
}
```

When a full page is returned, `nextCursor` is the last message’s `created_at` string; otherwise `null`.

### `POST /api/v1/messages` — `send`

Send outbound mail from the bound service mailbox.

**Headers (optional but recommended):**
- `Idempotency-Key: <string>` — remembered **24 hours**. Replay returns `200` `{ "ok": true, "id": "…", "idempotent": true }` instead of sending again.
- `Content-Type: application/json`

**Body:**

```json
{
  "to": "customer@example.com",
  "cc": "optional@example.com",
  "bcc": "optional@example.com",
  "subject": "Required, ≤ 150 characters",
  "text": "Plain text body",
  "html": "<p>Optional HTML</p>",
  "attachments": [
    {
      "filename": "receipt.pdf",
      "type": "application/pdf",
      "content": "<base64>"
    }
  ]
}
```

Rules:

- `to` and a body (`text` and/or `html`) are required.
- Subject is required, max **150** characters. API does **not** apply web-UI phishing phrase bans (`validateApiSubject` = length only).
- If only `html` is sent, plain text is derived by stripping tags; if only `text`, HTML is `\n` → `<br>\n`.
- Attachments: max **5** per email; each file ≤ **~30MB** raw; `content` is **base64**.

Response `201`:

```json
{ "ok": true, "id": "eml_01h…" }
```

### `GET /api/v1/messages/:id` — `read`

Full message + attachments metadata. Marks the message read (unless in trash). `404` if missing/draft.

```bash
curl https://mail.shaka.rw/api/v1/messages/eml_01h… \
  -H "Authorization: Bearer dm_live_YOUR_KEY"
```

Response `200` (detail `message` mirrors DB row shape: `is_read` / `is_draft` are `0`|`1` integers):

```json
{
  "message": {
    "id": "eml_01h…",
    "user_id": "mbx_01h…",
    "direction": "inbound",
    "from_addr": "customer@example.com",
    "to_addr": "noreply@yourdomain.com",
    "cc_addr": null,
    "bcc_addr": null,
    "subject": "Hello",
    "body_text": "Hi there…",
    "body_html": "<p>Hi there…</p>",
    "message_id": "<abc@example.com>",
    "in_reply_to": null,
    "reply_to_email_id": null,
    "is_read": 1,
    "is_draft": 0,
    "deleted_at": null,
    "created_at": "2026-08-03 12:00:00",
    "updated_at": null
  },
  "attachments": [
    {
      "id": "att_01h…",
      "email_id": "eml_01h…",
      "filename": "receipt.pdf",
      "content_type": "application/pdf",
      "size_bytes": 12044,
      "created_at": "2026-08-03 12:00:01"
    }
  ]
}
```

### `PATCH /api/v1/messages/:id` — `read`

Body (one action):

```json
{ "is_read": true }
```

or

```json
{ "restore": true }
```

```bash
curl -X PATCH https://mail.shaka.rw/api/v1/messages/eml_01h… \
  -H "Authorization: Bearer dm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_read": true }'
```

Response `200`:

```json
{ "ok": true }
```

### `DELETE /api/v1/messages/:id` — `read`

- Soft-delete (trash) by default.
- Permanent: `?hard=1` or `?permanent=1`, or delete again while already in trash.

```bash
curl -X DELETE https://mail.shaka.rw/api/v1/messages/eml_01h… \
  -H "Authorization: Bearer dm_live_YOUR_KEY"
```

Response `200` (soft):

```json
{ "ok": true, "permanent": false }
```

Hard delete → `{ "ok": true, "permanent": true }`.

### `POST /api/v1/messages/:id/reply` — `send`

Reply with threading (`In-Reply-To` / `References` from original). Subject becomes `Re: …` if needed. Recipient is the other party (inbound → original `from`, outbound → original `to`).

```json
{
  "text": "Thanks for your note.",
  "html": "<p>Optional</p>",
  "cc": "…",
  "bcc": "…",
  "attachments": [{ "filename": "…", "type": "…", "content": "<base64>" }]
}
```

Body (`text` and/or `html`) required.

```bash
curl -X POST https://mail.shaka.rw/api/v1/messages/eml_01h…/reply \
  -H "Authorization: Bearer dm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Thanks for your note." }'
```

Response `201`:

```json
{ "ok": true, "id": "eml_01h…" }
```

### `GET /api/v1/messages/:id/attachments/:attachmentId` — `read`

Binary download. `?download=1` forces attachment disposition; otherwise previewable types may be `inline`.

```bash
curl -OJ "https://mail.shaka.rw/api/v1/messages/eml_01h…/attachments/att_01h…?download=1" \
  -H "Authorization: Bearer dm_live_YOUR_KEY"
```

Response `200` — raw file bytes with `Content-Type` from the attachment, `Content-Length`, and `Content-Disposition` (`attachment` or `inline`). Not JSON.

## Inbound webhooks

Keys with `webhook` scope and a configured HTTPS webhook URL receive a signed `POST` when mail arrives at the bound mailbox.

**Headers:**
- `Content-Type: application/json`
- `X-Shaka-Signature: sha256=<hmac_hex>` — HMAC-SHA256 of the **raw request body** using the webhook secret (shown once at key creation)
- `X-Dime-Signature` — the same value under the legacy header name, kept for receivers built before the rename. New code should read `X-Shaka-Signature`.
- `User-Agent: Shaka-Webhooks/1.0`

**Payload (body your endpoint receives):**

```json
{
  "type": "message.received",
  "id": "<delivery_id>",
  "created_at": "2026-08-03T00:00:00.000Z",
  "data": {
    "message_id": "<email_id>",
    "from": "sender@example.com",
    "to": "noreply@yourdomain.com",
    "subject": "Hello",
    "snippet": "…",
    "has_attachments": false
  }
}
```

Verify `X-Shaka-Signature` with a timing-safe compare of `sha256=` + hex HMAC over the exact raw body. v1 is **best-effort with no retries**; deliveries are logged for audit. Fetch full content via `GET /api/v1/messages/:id` after verifying the webhook.

## Example: send mail

```bash
curl -X POST https://mail.shaka.rw/api/v1/messages \
  -H "Authorization: Bearer dm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-42-receipt" \
  -d '{
    "to": "customer@example.com",
    "subject": "Your verification code",
    "text": "Your code is 482913."
  }'
```

Response `201`:

```json
{ "ok": true, "id": "eml_01h…" }
```

Idempotent replay → `200` `{ "ok": true, "id": "eml_01h…", "idempotent": true }`.

## Example: verify webhook (Node)

```js
import crypto from 'node:crypto';

// rawBody: the exact bytes you received.
// header: request.headers['x-shaka-signature']
function verifyShakaSignature(rawBody, header, secret) {
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const received = Buffer.from(String(header ?? ''));
  const wanted = Buffer.from(expected);
  return received.length === wanted.length
    && crypto.timingSafeEqual(received, wanted);
}
```

## Integration checklist for coding agents

1. Store `dm_live_…` and webhook secret only in server env / secrets manager.
2. Call `https://mail.shaka.rw/api/v1/…` with Bearer auth; never from the browser.
3. Prefer `Idempotency-Key` on every send that might retry.
4. Keep subjects human and ≤ 150 chars.
5. On inbound webhook: verify `X-Shaka-Signature`, then `GET` the message by `data.message_id`.
6. Handle `{ error, code }` and HTTP status; treat `403` as missing scope configuration.