# LorePort API

Version 1. Base address: `https://loreport.ca/api/v1`

LorePort is a newsletter service for fiction authors. The API lets an author's website, a plugin, or their own tools read and manage their lists and subscribers, send signups, read newsletter results, and receive webhooks. This page is the whole reference, written so a person or an AI coding assistant can build an integration from it alone.

## The basics

- **Requests and responses are JSON.** Send `Content-Type: application/json` and `Accept: application/json`.
- **Every request needs an API key**, sent as a bearer token: `Authorization: Bearer lp_...`. Keys are made by the author in LorePort under **Settings → API and webhooks**. A key belongs to one account and has only the permissions chosen when it was made. Accounts start with no keys.
- **API access depends on the plan.** Paid plans include it. A key on a plan without it gets `403 plan_has_no_api`.
- **Keep keys secret.** Use them only from a server, never in a web page or app that readers can inspect. Anyone with a key can act on the account.
- **IDs** are opaque strings (26 characters). **Times** are ISO 8601 in UTC, such as `2026-11-13T18:04:00Z`. Email addresses are stored lowercase.
- **Versioning:** everything is under `/v1`. Additions (new fields, new endpoints) can appear in v1 at any time, so ignore fields you don't know. Anything that would break an integration gets a new version.

### Permissions

| Permission | Allows |
|---|---|
| `lists:read` | Read pen names, lists and tags |
| `subscribers:read` | Read subscribers |
| `subscribers:write` | Add, edit, tag and unsubscribe subscribers |
| `signups:write` | Send signups, as from a signup form |
| `newsletters:read` | Read newsletters and their opens and clicks |
| `books:read` | Read books, signup links and their numbers |
| `usage:read` | Read the plan and usage |

`GET /me` works with any key.

### Errors

Errors always look like this, with an HTTP status to match:

```json
{"error": {"code": "invalid", "message": "The email field is required.", "fields": {"email": ["The email field is required."]}}}
```

| Status | `code` | Meaning |
|---|---|---|
| 401 | `unauthenticated` | Missing, wrong or revoked key |
| 403 | `plan_has_no_api` | The account's plan doesn't include the API |
| 403 | `missing_permission` | The key lacks the permission this endpoint needs |
| 404 | `not_found` | No such record in this account (another account's IDs are always "not found") |
| 422 | `invalid` | The request didn't pass checks; `fields` says which and why |
| 429 | `rate_limited` | Too many requests; wait `Retry-After` seconds |
| 500 | `server_error` | Our fault; it's logged |

### Rate limits

Each key may make 120 requests a minute. Every response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`. Over the limit, you get `429` with a `Retry-After` header (seconds).

### Pages of results

Lists of subscribers, newsletters, books and signup links come in pages: `?page=2&per_page=50` (`per_page` up to 100, default 25).

```json
{"data": [ ... ], "meta": {"page": 2, "per_page": 50, "total": 1234, "has_more": true}}
```

Keep asking for the next page while `has_more` is true.

## Consent: subscribers versus signups

LorePort keeps a consent record for every subscriber, as anti-spam laws (CASL, GDPR, CAN-SPAM) require. There are two ways to add someone, and the difference matters:

- **`POST /signups`: a reader signing up themselves** on the author's site or app. It's treated exactly like a LorePort signup form. If the list uses double opt-in, the reader is `pending` and gets a confirmation email; they're `subscribed` once they click it. Someone who unsubscribed may rejoin this way. Send the reader's IP address and browser (`ip`, `user_agent`) so the consent record is complete.
- **`POST /subscribers`: the author adding someone** who already agreed some other way (at an event, by email). Requires `"consent": true`. No confirmation email; they're `subscribed` straight away. Someone who unsubscribed from the list can't be added back this way: only they can rejoin.

Either way, blocked addresses (bounced, marked as spam, erased, or blocked by the author) are refused.

## Account

### GET /me

Who the key belongs to.

```json
{"data": {"account": {"id": "01jc...", "name": "Ada Starling Books"}, "key": {"id": "01jd...", "name": "My website", "prefix": "lp_a1B2c3D", "abilities": ["lists:read", "signups:write"]}}}
```

### DELETE /me

Any key. Revokes the key making the request, straight away: use it when your site or app disconnects from LorePort, so the key stops working. Answers `{"data": {"revoked": true, "prefix": "lp_a1B2c3D"}}`.

### GET /pen-names

`lists:read`. The account's pen names: `id`, `name`, `from_email`, `url` (the pen name's home page, such as `https://loreport.ca/k4m9/jane-doe`) and `page_published` (true when readers can see that page; otherwise `url` is "not found" for them).

### GET /lists

`lists:read`. Every list:

```json
{"data": [{"id": "01jc...", "name": "Starling Readers", "pen_name_id": "01jb...", "double_opt_in": true, "consent_text": "Yes, email me news about new books...", "color": "#cfe3ff", "url": "https://loreport.ca/k4m9/jane-doe/starling-readers", "page_public": true, "created_at": "2026-11-10T15:00:00Z"}]}
```

`url` is the list's signup page. When `page_public` is false the author has turned the page off: readers who open it get "not found", but forms that post to it (and `POST /signups`) still work.

### GET /lists/{id}

`lists:read`. One list, plus `counts`: `{"subscribed": 812, "pending": 14, "unsubscribed": 40}`.

### GET /tags

`lists:read`. Every tag: `id`, `name`.

### GET /usage

`usage:read`. The plan and this month's usage. A `limit` of `null` means no limit.

```json
{"data": {"plan": {"key": "novella", "name": "Novella"}, "period": "2026-11", "subscribers": {"used": 826, "limit": 5000}, "emails_this_month": {"used": 2400, "limit": 25000}}}
```

## Subscribers

A subscriber is one person (one email address) in the account, on one or more lists.

```json
{
  "id": "01jf...",
  "email": "reader@example.com",
  "name": "Sam Reader",
  "lists": [
    {"list_id": "01jc...", "status": "subscribed", "consent_source": "form", "consented_at": "2026-11-12T09:30:00Z", "confirmed_at": "2026-11-12T09:31:10Z", "unsubscribed_at": null}
  ],
  "tags": ["ARC reader"],
  "newsletters_opened": 7,
  "opened_automatically_only": 1,
  "link_clicks": 3,
  "created_at": "2026-11-12T09:30:00Z"
}
```

- `status` on a list: `subscribed`, `pending` (signed up, hasn't confirmed by email yet) or `unsubscribed`.
- `consent_source`: `form`, `api` (from `/signups`), `import` or `manual` (added by the author).
- `newsletters_opened` counts newsletters opened by a person, when the pen name tracks opens. `opened_automatically_only` counts newsletters that were only opened automatically (Apple Mail loads every email's images), so they may not have been read. `link_clicks` leaves out mail scanners.

### GET /subscribers

`subscribers:read`. Filters, all optional:

| Parameter | |
|---|---|
| `email` | Exactly this address (the quickest way to look someone up) |
| `search` | Part of an email or name |
| `list` | A list ID: only people on it |
| `status` | `subscribed`, `pending` or `unsubscribed` (on `list` if given, else on any list) |
| `tag` | A tag ID |
| `sort` | `joined` (default), `email`, `name`, `opens` or `clicks` |
| `dir` | `desc` (default) or `asc` |
| `page`, `per_page` | See "Pages of results" |

### GET /subscribers/{id}

`subscribers:read`. One subscriber.

### POST /subscribers

`subscribers:write`. The author adds someone who agreed to receive their emails (see "Consent").

```json
{"email": "reader@example.com", "name": "Sam Reader", "list_id": "01jc...", "consent": true, "consent_text": "Signed up at the Toronto book fair, 2026-11-08.", "confirm": false}
```

`consent_text` (optional, but say how they agreed: Canadian and EU law expect a record) is recorded as how they agreed. Add `"confirm": true` to have LorePort email them a confirmation link first; they're added when they click it. Answers `201` with `outcome` `subscribed` (or `pending_confirmation` with `confirm`), or `200` with `already_subscribed`, and the subscriber in `data`. Refused with `422` if the address is blocked, or they unsubscribed from that list.

Don't use `/signups` for people you add yourself: it records them as having signed up on your site.

### PATCH /subscribers/{id}

`subscribers:write`. Change `name` and/or `email`. An email change is for the same person (a typo, or a new address they told the author about): they keep their lists and consent. It can't be an address another subscriber has, or a blocked one.

### POST /subscribers/{id}/tags

`subscribers:write`. `{"tag": "ARC reader"}`. Creates the tag if it's new. Returns the subscriber.

### DELETE /subscribers/{id}/tags/{tag name}

`subscribers:write`. Removes a tag (URL-encode the name). Returns the subscriber.

### POST /subscribers/{id}/unsubscribe

`subscribers:write`. `{"list_id": "01jc..."}` to unsubscribe from one list, or `{}` for all of them. Returns the subscriber.

## Signups

### POST /signups

`signups:write`. A reader signing up on the author's site (see "Consent"). Use this behind your own signup form.

```json
{"email": "reader@example.com", "name": "Sam", "list_id": "01jc...", "ip": "203.0.113.7", "user_agent": "Mozilla/5.0 ...", "source": "homepage-form", "tags": ["Book 2 page"]}
```

- `ip` and `user_agent`: the reader's, from your server's request. Recorded with their consent.
- `consent_text`: what they agreed to, if your form words it differently from the list's statement.
- `source`: a short label for where on your site it came from.
- `tags`: up to 10 tag names (64 characters each) to add to the reader, such as the book page they signed up on. New tags are created. They're added even when the reader is already subscribed or still has to confirm, but never to a blocked address. Set them from your own code, not from what the reader sends.

Answers `201` with `outcome` `pending_confirmation` (they've been emailed a confirmation link) or `subscribed` (lists without double opt-in), or `200` with `already_subscribed`. A blocked address is refused with `422`; tell the reader to contact the author.

## Newsletters

### GET /newsletters

`newsletters:read`. Newest first. Filters: `status` (`draft`, `scheduled`, `sending`, `sent`), `list` (a list ID), `page`, `per_page`.

```json
{"id": "01jg...", "subject": "Book 3 is out!", "preview_text": null, "list_id": "01jc...", "status": "sent", "track_clicks": true, "track_opens": false, "scheduled_at": null, "started_at": "2026-11-12T16:00:00Z", "finished_at": "2026-11-12T16:03:00Z", "created_at": "2026-11-11T10:00:00Z"}
```

### GET /newsletters/{id}

`newsletters:read`. One newsletter with its results:

```json
{
  "data": {
    "id": "01jg...", "subject": "Book 3 is out!", "status": "sent", "...": "...",
    "stats": {"sent": 812, "not_sent": 3, "waiting": 0, "bounced": 2, "complained": 0, "unsubscribed": 4, "opened_by": null, "opened_automatically_only": null, "clicked_by": 133},
    "links": [{"url": "https://example.com/book-3", "clicks": 160, "readers": 121, "automated_clicks": 18}]
  }
}
```

`opened_by` is `null` when open tracking was off for it, and `clicked_by` and `links` are empty when click tracking was off. Clicks by mail scanners are counted separately and left out of `clicks` and `readers`.

## Books and signup links

Each book can have a public page, and each signup link is a signup page for one place the author shares it (an ebook's back matter, a bookmark, a convention). Both live at the author's public address, such as `https://loreport.ca/k4m9/jane-doe/bonus-epilogue`; use the `url` field rather than building it. Old addresses redirect after a rename, so a saved `url` keeps working.

### GET /books

`books:read`. By title. Filters: `pen_name` (a pen name ID), `page`, `per_page`.

```json
{
  "id": "01jk...", "pen_name_id": "01jb...", "title": "The Starling Gambit", "subtitle": null,
  "series_name": "The Drowned Coast", "series_number": "2", "blurb": "A map that redraws itself every night.",
  "cover_url": "https://...", "release_date": "2027-03-04",
  "url": "https://loreport.ca/k4m9/jane-doe/the-starling-gambit", "page_published": true, "signup_list_id": "01jc...",
  "formats": [{"id": "01jm...", "format": "ebook", "isbn": "9780306406157", "asin": "B0C1234567"}],
  "retailer_links": [{"id": "01jn...", "retailer": "kobo", "name": "Kobo", "url": "https://www.kobo.com/...", "format_id": null}],
  "created_at": "2026-11-16T10:00:00Z"
}
```

- `release_date` is a date (`YYYY-MM-DD`) or `null`. A date in the future means the book is upcoming (its page offers pre-orders).
- `format` is `ebook`, `paperback`, `hardcover`, `audiobook` or `large_print`. `retailer` is `amazon`, `apple_books`, `kobo`, `barnes_noble`, `google_play`, `bookshop`, `audible`, `own_store` or `other`; `name` is what the button says (the author's own name for `other`). `format_id` ties a link to one of the book's formats, or is `null` for any format. Both lists are in the author's order.
- `page_published` is false while the author hasn't published the book's page: readers who open `url` then get "not found". `signup_list_id` is the list the page's signup form joins, or `null` for no form.

### GET /books/{id}

`books:read`. One book, as above.

### GET /signup-links

`books:read`. Newest first. Filters: `book` (a book ID), `pen_name` (a pen name ID), `period` (see below), `page`, `per_page`.

```json
{
  "id": "01jp...", "pen_name_id": "01jb...", "list_id": "01jc...", "book_id": "01jk...",
  "label": "Ebook back matter", "url": "https://loreport.ca/k4m9/jane-doe/bonus-epilogue",
  "heading": "Get the bonus epilogue", "description": null, "button": null, "tags": ["Bonus epilogue"],
  "active": true, "ended_at": null,
  "numbers": {"visits": 412, "signups": 96, "readers": 88},
  "created_at": "2026-11-16T10:00:00Z"
}
```

- `label` is the author's own note of where the link is used; readers don't see it. `heading`, `description` and `button` are `null` when the page uses LorePort's defaults. Everyone who joins through the link gets `tags`.
- `active` is false when the author has turned the link off (its page then says it has ended; `ended_at` says when) or its list was deleted (`list_id` is then `null`).
- `numbers`: `visits` to the page (robots and link previews aren't counted), `signups` (new subscriptions only: a reader already on the list isn't counted again), and `readers` (people who joined through it and are on the list now, either confirmed or on a list that doesn't ask them to confirm).
- `period`: `30`, `90` or `365` (the last that many days, today included) or `all` (the default).

### GET /signup-links/{id}

`books:read`. One signup link, as above, with `period` as above.

## Embedded pages (website plugins)

### POST /embed-sessions

`dashboard:embed`. For the WordPress and Statamic plugins: a sign-in link that opens LorePort's own Subscribers, Lists or Newsletters pages inside a frame in the website's admin.

```json
{"path": "/subscribers"}
```

Answers `201`:

```json
{"data": {"url": "https://loreport.ca/embed/start/...", "expires_at": "2026-11-14T15:00:00Z", "origin": "https://janedoebooks.com"}}
```

- The key needs a **website** set in LorePort (Settings → API and webhooks). Only that site may show the pages; without it the answer is `403` `no_website`.
- `path` (optional, default `/subscribers`) must be a Subscribers, Lists or Newsletters page.
- The link works once, within a minute: get a fresh one each time the page loads, and open it in the frame (`<iframe src="...">`), never in a top-level window.
- The frame's session lasts as long as a normal LorePort sign-in (kept alive while the page is open and its tab visible), and ends when the key is revoked, loses the permission or changes website. Other pages (pen names, plan, billing, sending setup) open LorePort in a new tab.
- Inside the frame, each page tells the parent window where it is: `postMessage({source: "loreport", type: "navigate", path, title})`, sent to the key's website only. It's sent again whenever the address changes inside a page (filters, searches, sorting, page numbers), so `path` can carry a query string. Use it to keep your own page's address in step, so reloading returns to the same page with the same filters. When the frame's session has ended (it timed out after a long idle spell, or the key changed), it sends `{source: "loreport", type: "expired", path}` instead: ask for a new link with that `path` and load it in the frame. Don't retry more than once a minute or so: if the new link ends the same way, the browser is blocking the frame's cookie, and the frame shows "Open LorePort".

## Webhooks

LorePort can tell your server when something happens. Add an endpoint in LorePort under **Settings → API and webhooks**: an `https://` address and the events you want. You get a signing secret (`whsec_...`) once, when you add it.

### Events

| Event | When |
|---|---|
| `subscriber.subscribed` | Someone subscribed to a list directly (no confirmation needed), or rejoined |
| `subscriber.pending` | Someone signed up and was sent a confirmation email |
| `subscriber.confirmed` | Someone confirmed by email; they're now subscribed |
| `subscriber.unsubscribed` | Someone unsubscribed from a list (by link, by the author, or through the API) |
| `webhook.test` | The "Send test" button |

### What arrives

A `POST` with a JSON body:

```json
{
  "id": "01jh...",
  "type": "subscriber.confirmed",
  "created_at": "2026-11-13T18:04:00Z",
  "data": {
    "subscriber": { "...": "the subscriber, as in the API" },
    "list": { "...": "the list, as in the API" },
    "status": "subscribed"
  }
}
```

Headers: `LorePort-Event` (the type), `LorePort-Delivery` (the same as `id`; unique per delivery, so use it to ignore repeats), and `LorePort-Signature`.

Answer with any `2xx` status within 10 seconds. Anything else, or no answer, is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours. After 20 failed deliveries in a row the endpoint is turned off; turn it back on in Settings. Deliveries can arrive out of order, and very rarely more than once.

### Checking the signature

`LorePort-Signature` looks like `t=1763057040,v1=5f2b...`. `v1` is the hex HMAC-SHA256, keyed with your signing secret, of the timestamp, a full stop, and the raw request body: `t + "." + body`. Compute it yourself and compare in constant time. Also reject anything whose `t` is more than 5 minutes old, so a recorded message can't be replayed.

PHP:

```php
$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_LOREPORT_SIGNATURE'] ?? ''), $sig);
$expected = hash_hmac('sha256', ($sig['t'] ?? '').'.'.$body, getenv('LOREPORT_WEBHOOK_SECRET'));
if (! hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int) ($sig['t'] ?? 0)) > 300) {
    http_response_code(400);
    exit;
}
$event = json_decode($body, true);
```

Node.js:

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

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300;
  return fresh && parts.v1?.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
```

Check the signature against the raw body exactly as received, before parsing it.

## Examples

Look someone up by email:

```sh
curl -s "https://loreport.ca/api/v1/subscribers?email=reader@example.com" \
  -H "Authorization: Bearer $LOREPORT_KEY" -H "Accept: application/json"
```

Send a signup from your own form handler:

```sh
curl -s -X POST "https://loreport.ca/api/v1/signups" \
  -H "Authorization: Bearer $LOREPORT_KEY" -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"email":"reader@example.com","name":"Sam","list_id":"01jc...","ip":"203.0.113.7"}'
```

## Notes for AI coding assistants

- Ask the author for an API key with only the permissions the integration needs, and keep it in server-side configuration (an environment variable), never in front-end code.
- For a signup form on the author's site, call `POST /signups` from the server, passing the reader's IP and user agent. Don't use `POST /subscribers` for that: it skips the confirmation email that double opt-in lists rely on.
- Get list IDs from `GET /lists` (or ask the author which list) rather than hard-coding them without checking.
- Handle `422` by showing the reader a friendly message; `fields` says what was wrong. Handle `429` by waiting `Retry-After` seconds.
- For webhooks, verify `LorePort-Signature` before trusting a message, and use `LorePort-Delivery` to skip repeats.
- This guide is at `https://loreport.ca/docs/loreport.md`; `https://loreport.ca/llms.txt` points to it.
