> ## Documentation Index
> Fetch the complete documentation index at: https://docs.railmail.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> From an API key to your first subscribed user in minutes.

This guide takes you from zero to a subscriber added to one of your topics, using the [Railmail Public API](/en/api-reference/introduction).

## 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](https://app.railmail.app).
* A tool to make HTTP requests — `curl`, Postman, or your language's HTTP client.

<Tip>
  Use a `rm_test_...` key while you're integrating so you don't touch live data.
</Tip>

## Add a subscriber to a topic

<Steps>
  <Step title="Set your API key">
    Store your key in an environment variable so you don't paste it into every request.

    ```bash theme={null}
    export RAILMAIL_API_KEY="rm_test_your_key_here"
    ```
  </Step>

  <Step title="Discover your topic keys">
    List the topics in your project and note the `topicKey` you want to subscribe users to.

    ```bash theme={null}
    curl https://api.railmail.app/api/v1/topics \
      -H "X-API-Key: $RAILMAIL_API_KEY"
    ```
  </Step>

  <Step title="Create a subscriber and subscribe them">
    Create the subscriber and subscribe them to the topic in a single call by passing `topicKeys` and `consent`.

    ```bash theme={null}
    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.
  </Step>

  <Step title="Verify">
    Read the subscriber back to confirm the subscription.

    ```bash theme={null}
    curl https://api.railmail.app/api/v1/subscribers/user@example.com \
      -H "X-API-Key: $RAILMAIL_API_KEY"
    ```
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Explore all endpoints" icon="code" href="/en/api-reference/introduction">
    Browse subscribers, campaigns, segments, automations and more.
  </Card>

  <Card title="Authentication & scopes" icon="key" href="/en/api-reference/authentication">
    Understand what each key can do and how to keep it secure.
  </Card>
</CardGroup>

<Tip>
  Need help? Reach out at [support@railmail.app](mailto:support@railmail.app).
</Tip>