# Pombo Mailer

> Pombo is a newsletter publishing platform with a versioned JSON API for authentication, newsletters, issues, and bookmarks.

## API documentation

- Human guide: https://pombomailer.com/docs/api
- Plain Markdown guide: https://pombomailer.com/docs/api.md
- OpenAPI 3.1 YAML: https://pombomailer.com/openapi.yaml
- OpenAPI 3.1 JSON: https://pombomailer.com/openapi.json

## Authentication

The API uses bearer tokens obtained through a browser-based device authorization flow. Start with `POST /api/v1/auth/device`, open `verification_uri_complete`, then poll `POST /api/v1/auth/token` no more often than the returned interval. Device codes expire and can be exchanged only once.

Authenticated requests use `Authorization: Bearer pombo_...`.

## Core workflows

- `GET /api/v1/me` returns the authenticated account.
- `GET /api/v1/newsletters` lists newsletters the account owns or can edit.
- `GET /api/v1/newsletters/{newsletter_id}/issues` lists issues newest first and includes `created_at` and `status`.
- `POST /api/v1/newsletters/{newsletter_id}/issues` creates a draft.
- `PATCH /api/v1/newsletters/{newsletter_id}/issues/{issue_id}` updates an issue.
- `GET /api/v1/newsletters/{newsletter_id}/bookmarks` returns bookmarks as HTML.
- `DELETE /api/v1/auth/token` revokes the current token.

Use the OpenAPI document as the authoritative endpoint and schema reference. Use the Markdown guide for authentication behavior and workflow examples.