Authentication

Clients should authenticate by passing the token key in the Authorization HTTP header, prepended with the string Token (note the trailing space!).

For example, an authenticated request to list your subscribers looks like this:

import requests

url = "https://api.buttondown.com/v1/subscribers"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}

response = requests.request("GET", url, headers=headers)
print(response.text)

You can manage your API keys at API → Keys.

You can create as many API keys as you need. This is useful when you have different integrations that need different levels of access:

• A Zapier workflow that adds new subscribers might only need write access to subscribers
• An analytics dashboard might only need read access to emails and subscribers
• A custom script that sends emails might need sending access but nothing else

Each key can have its own label (like "Zapier - new subscribers" or "Internal dashboard") so you can keep track of what each one is for. If one integration is compromised or you stop using it, you can delete or regenerate just that key without affecting your other integrations.

One key is special: your account's primary API key. It always has full access — you can't change its permissions — and it can't be deleted. If a primary key leaks, regenerate it to invalidate the current value.

Each API key can be configured with independent permissions for different parts of the API:

Each permission can be set to:

• write — full access to create, update, and delete
• read — can view but not modify
• none — no access

If you attempt an operation that your API key doesn't have permission for, you'll receive a 403 Forbidden response.

If you're using the API to manage multiple newsletters, you can pass the Buttondown-Context header to specify the newsletter you want to access.

Consider the following example, in which a single platform account manages multiple newsletters. Each newsletter has its own API key in addition to the platform account's API key:

flowchart TD
    A[sheinhardt] -->|owns| B[sheinhardt_pt]
    A[sheinhardt] -->|owns| C[sheinhardt_fr]
    A[sheinhardt] -->|owns| D[sheinhardt_de]
    A[sheinhardt] -->|owns| E[sheinhardt_en]

    subgraph A[sheinhardt]
       api_key_111
    end

    subgraph B[sheinhardt_pt]
       api_key_111_b
    end

    subgraph C[sheinhardt_fr]
       api_key_111_c
    end

    subgraph D[sheinhardt_de]
       api_key_111_d
    end

    subgraph E[sheinhardt_en]
       api_key_111_e
    end

The platform could programmatically access each newsletter's API key and pass it through, but this is clumsy and onerous. Instead, you can authenticate with the platform account's own API key and pass the Buttondown-Context header to specify which newsletter you want to act on:

import requests

url = "https://api.buttondown.com/v1/subscribers"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY",
  "Buttondown-Context": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}

response = requests.request("GET", url, headers=headers)
print(response.text)

The value of Buttondown-Context must be the newsletter's ID — a UUID, not its username. You can find a newsletter's ID by listing your newsletters at GET /v1/newsletters. The header works with every endpoint: reads (/subscribers, /emails, /imports, …) return the target newsletter's data, and writes (creating a draft, inviting a user via POST /users) are scoped to it.

Two constraints are worth calling out:

• The header only takes effect when you authenticate with the platform account's API key and the account has access to the target newsletter. It does not let one newsletter's key reach into another.
• If the header value isn't the ID of a newsletter you can access — an unknown ID, a malformed value, or a newsletter's username — the request fails with 401 authentication_invalid. It never falls back to the account's primary newsletter, so a typo can't silently send a request to the wrong place.