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:

{"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).

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

Keep asking for the next page while has_more is true.

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.

{"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:

{"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.

{"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.

{
  "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").

{"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.

{"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.

{"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:

{
  "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.

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.

{
  "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.

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

{
  "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.

{"path": "/subscribers"}

Answers 201:

{"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:

{
  "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:

$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:

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:

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:

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.