For AI Agents

# SeRSSly API Reference — For AI Agents
# https://serssly.com

## What is SeRSSly?
Email-to-RSS service. Create @serssly.com email addresses, subscribe them
to newsletters, read the content as RSS feeds. All via REST API.

## Authentication
All requests require: Authorization: Token <api-key>
The key is typically in env var SERSSLY_API_KEY.

## Base URL
https://serssly.com/api/v1

## Endpoints

### Email Addresses
GET    /email_addresses
  List all addresses. Paginated (keyset). Returns email_addresses[] + pagination.

GET    /email_addresses/:id
  Get a single address.

POST   /email_addresses
  Body: {"name": "Label", "folder_id": null}
  Both fields optional. Returns new address with rss_token.
  The email is: {rss_token}@serssly.com
  The RSS feed is: https://serssly.com/e/{rss_token}.rss

PATCH  /email_addresses/:id
  Body: {"name": "New Label", "folder_id": "uuid"}

DELETE /email_addresses/:id
  Deletes address and all its emails. Returns 204.

### Emails
GET    /email_addresses/:id/emails
  List received emails for an address. Newest first. Paginated.
  Each email has: id, sender, to, cc, subject, body_text, body_html,
  body_markdown, body_raw, received_at.

DELETE /emails/:id
  Delete a single email. Returns 204.

### Folders
GET    /folders
  List root folders with nested children and email_addresses included.

POST   /folders
  Body: {"name": "Folder Name", "parent_id": null}
  name is required. parent_id enables nesting.

PATCH  /folders/:id
  Body: {"name": "New Name", "parent_id": "uuid"}

DELETE /folders/:id
  Deletes folder. Addresses in it are unassigned, not deleted. Returns 204.

Folder RSS feed: https://serssly.com/f/{folder_rss_token}.rss
  Combines all emails from all addresses in the folder and subfolders.

### API Keys
GET    /api_keys
  List all keys. Token is NEVER shown in list responses.

POST   /api_keys
  Body: {"name": "Key Name"}
  name is required. Response includes "token" field ONCE. Save it.

DELETE /api_keys/:id
  Revoke a key immediately. Returns 204.

### Account
GET    /account
  Returns plan, limits, usage, renewal info.
  { plan, display_name, price_cents, limits, usage, renews_at, cancel_at_period_end }

POST   /account/checkout_url
  Body: {"price": "starter"|"standard"|"premium"}
  Returns {"url": "..."} to upgrade plan via Stripe Checkout.

POST   /account/portal_url
  Returns {"url": "..."} to manage subscription via Stripe Customer Portal.

## RSS Feeds (no auth required)
GET /e/{token}.rss  — RSS feed for a single email address
GET /f/{token}.rss  — RSS feed for a folder (includes subfolders)

Feeds are RSS 2.0. Items contain full HTML content with inlined CSS.
Feed URLs are unguessable (token-based) but require no authentication.

## Pagination
List endpoints return the resource under its own key (e.g. "email_addresses"
for GET /email_addresses, "emails" for GET /email_addresses/:id/emails) plus
"pagination": { "limit": 20, "next_url": "...", "previous_url": "..." }.
Follow next_url to get the next page. null means no more pages.

## Errors
401 — Bad or missing token
402 — Plan limit exceeded (include upgrade_url in future)
404 — Not found or belongs to another user
422 — Validation error, check "errors" array

## Common Workflows

# Create a feed for a newsletter:
1. POST /email_addresses {"name": "Newsletter Name"}
2. Tell user to subscribe at the newsletter using the returned email
3. Read new issues via GET /e/{token}.rss or GET /email_addresses/:id/emails

# Organize feeds into a folder:
1. POST /folders {"name": "Tech"}
2. POST /email_addresses {"name": "Feed 1", "folder_id": folder_id}
3. Read all feeds combined via GET /f/{folder_token}.rss

# Summarize recent newsletters:
1. GET /email_addresses/:id/emails (get latest emails)
2. Read body_text or body_markdown fields
3. Summarize the content for the user