Developer documentation
Pombo API
Authenticate a CLI or agent, discover newsletters, manage draft issues, and retrieve bookmarks through the Pombo JSON API.
Base URL
https://pombomailer.com/api/v1
Authentication
API requests use a bearer token obtained through the device authorization flow. Start the flow, open the returned URL in a browser, and poll at the response's requested interval until the user approves access.
Authorization: Bearer pombo_...
POST /api/v1/auth/device- Open
verification_uri_completein the user's browser. POST /api/v1/auth/tokenwith the returneddevice_code.
Device codes expire and can only be exchanged once. Access tokens remain
valid until revoked with DELETE /api/v1/auth/token, or from the
Authorized devices section of your profile.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| POST | /api/v1/auth/device | Start authorization |
| POST | /api/v1/auth/token | Exchange a device code |
| GET | /api/v1/me | Current account |
| GET | /api/v1/newsletters | Accessible newsletters |
| GET | /api/v1/newsletters/:id/issues | Issues, newest first |
| POST | /api/v1/newsletters/:id/issues | Create a draft |
| PATCH | /api/v1/newsletters/:id/issues/:id | Update an issue |
| GET | /api/v1/newsletters/:id/bookmarks | Bookmarks as HTML |
Find the latest draft
Issue lists are ordered newest first by created_at. Select the
first record whose status is draft.
Create an issue
curl -X POST https://pombomailer.com/api/v1/newsletters/NEWSLETTER_ID/issues \
-H "Authorization: Bearer $POMBO_TOKEN" \
-H "Content-Type: application/json" \
-d '{"issue":{"subject":"New issue","content":"<p>Hello</p>"}}'
Issues created through the API always start as drafts.
Update an issue
curl -X PATCH https://pombomailer.com/api/v1/newsletters/NEWSLETTER_ID/issues/ISSUE_ID \
-H "Authorization: Bearer $POMBO_TOKEN" \
-H "Content-Type: application/json" \
-d '{"issue":{"meta_title":"Search title","content":"<p>Updated</p>"}}'
OpenGraph image
Issue responses include og_image_url, the public URL of the
attached OpenGraph image, or null when no image is attached.
Upload a new image with a multipart request:
curl -X PATCH https://pombomailer.com/api/v1/newsletters/NEWSLETTER_ID/issues/ISSUE_ID \
-H "Authorization: Bearer $POMBO_TOKEN" \
-F "issue[og_image]=@open-graph.png"
In a JSON request, og_image accepts an Active Storage signed
blob id from POST /rails/active_storage/direct_uploads, and
null removes the current image.
Errors
Errors use a stable machine-readable code and a human-readable description:
{"error":"not_found","error_description":"The requested resource was not found."}
Complete reference
Request schemas, response schemas, examples, and all error responses are available in the OpenAPI specification. Agents can also use the plain Markdown guide and llms.txt discovery file.