API quickstart - Railmail

This guide takes you from zero to a subscriber added to one of your topics, using the Railmail Public API.

Looking for your first steps in the Railmail app instead? See Getting started in the User Guide.

Prerequisites

Before you begin, you need:

A Railmail project with a project-scoped API key (format rm_live_... or rm_test_...). Create one in the app under Settings → API Keys; see API keys. For this guide the key needs the topics:read and subscribers:write scopes (or Full access).
A tool to make HTTP requests: curl, Postman, or your language’s HTTP client.

Use a rm_test_... key while you’re integrating so you don’t touch live data.

Add a subscriber to a topic

Set your API key

Store your key in an environment variable so you don’t paste it into every request.

export RAILMAIL_API_KEY="rm_test_your_key_here"

Discover your topic keys

List the topics in your project and note the topicKey you want to subscribe users to.

curl https://api.railmail.app/api/v1/topics \
  -H "X-API-Key: $RAILMAIL_API_KEY"

Create a subscriber and subscribe them

Create the subscriber and subscribe them to the topic in a single call by passing topicKeys and consent.

curl -X POST https://api.railmail.app/api/v1/subscribers \
  -H "X-API-Key: $RAILMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "topicKeys": ["newsletter"],
    "consent": "GRANTED"
  }'

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

Verify

Read the subscriber back to confirm the subscription.

curl https://api.railmail.app/api/v1/subscribers/user@example.com \
  -H "X-API-Key: $RAILMAIL_API_KEY"

Next steps

Explore all endpoints

Browse subscribers, campaigns, segments, automations and more.

Authentication & scopes

Understand what each key can do and how to keep it secure.

Need help? Reach out at support@railmail.app.

​Prerequisites

​Add a subscriber to a topic

​Next steps

Explore all endpoints

Authentication & scopes

Prerequisites

Add a subscriber to a topic

Next steps