Skip to main content
The Railmail Public API lets you manage subscribers, topics, consents, campaigns, segments, automations and more — programmatically. It is a REST API that speaks JSON, uses standard HTTP verbs, and returns conventional status codes.

​
Base URL

All endpoints are served from a single base URL: 
https://api.railmail.app
Every path in this reference is relative to that base and prefixed with /api/v1. For example, listing subscribers is GET https://api.railmail.app/api/v1/subscribers.

​
Authentication in one line

Every request must carry a project-scoped API key in the X-API-Key header: 
curl https://api.railmail.app/api/v1/subscribers \
  -H "X-API-Key: rm_live_your_key_here"
See Authentication for key formats, scopes and the Authorization: Bearer alternative.

​
Project isolation

A key resolves to exactly one project. All reads and writes are automatically isolated to that project and its tenant — a key can never read or modify another project’s data. You do not pass a project or tenant identifier; the key determines it.

​
Conventions

JSON everywhere

Request and response bodies are application/json. Errors use application/problem+json (RFC 7807).

Standard verbs

GET reads, POST creates, PATCH updates, DELETE removes. Verbs behave as you’d expect.

Scoped keys

Each operation requires a specific scope, listed in its description. A missing scope returns 403.

Rate limited

60 requests per minute per key. See Rate limits.

​
Canonical flow: add your users to your topics

A common first integration — subscribe your users to a topic:
1

Discover topic keys

Call GET /api/v1/topics to list the topics in your project and read their topicKey values.
2

Create and subscribe in one call

Call POST /api/v1/subscribers with topicKeys + consent to create a subscriber and subscribe them at once — or POST /api/v1/subscribers/{email}/consents to subscribe an existing subscriber.
3

Handle double opt-in

If a topic uses double opt-in, the consent is created PENDING_CONFIRMATION. The subscriber must confirm via the email they receive before they count as subscribed.

​
Test the endpoints

Every endpoint page in this reference includes an interactive playground. Enter your API key once and send real requests straight from the docs.