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

​
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 dashboard.
  • 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

1

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"
2

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"
3

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.
4

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.