Buttondown Documentation

Buttondown Documentation

© 2016–2024 Buttondown LLC.

TwitterDiscord GitHubLinkedInMastodonBlueskyFacebook

Creating a subscriber

info

This endpoint is for creating a new subscriber via the API. If you're looking to just do this via the UI, this doc is for you.

By default, newly created subscribers are subject to double opt-in — they will receive an email asking them to confirm their subscription, and have a state of unactivated until they do so.

You can't disable this behavior globally, but you can disable it on a per-subscriber basis by providing a type of regular in the request body.

Sample requests

These sample requests are autogenerated by the OpenAPI spec.

import requests

url = "https://api.buttondown.com/v1/subscribers"

payload = {
    "email_address": "telemachus@buttondown.email",
    "type": "regular"
}
headers = {
    "accept": "application/json",
    "authorization": "Token $BUTTONDOWN_API_KEY",
    "content-type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Sample responses

The IDs and values referenced in these responses are fake; please only rely on these responses for overall structure.

{
    "id": "13121cd6-0dfc-424c-bb12-988b0a32fcb3",
    "creation_date": "2020-09-29T00:00:00+00:00",
    "email_address": "telemachus@buttondown.email",
    "notes": "",
    "metadata": {
        "name": "Telemachus"
    },
    "tags": [],
    "referrer_url": "",
    "secondary_id": 1,
    "type": "unactivated",
    "source": "organic",
    "utm_campaign": "",
    "utm_medium": "",
    "utm_source": "",
    "referral_code": "",
    "avatar_url": "",
    "stripe_coupon": null,
    "unsubscription_date": null,
    "churn_date": null,
    "unsubscription_reason": "",
    "transitions": [],
    "ip_address": null,
    "last_open_date": null,
    "last_click_date": null,
    "stripe_customer_id": null,
    "stripe_customer": null,
    "subscriber_import_id": null
}

Body parameters

All parameters are optional unless explicitly specified.

email_address

Type
string · required
Example
"telemachus@buttondown.email"

notes

Type
string

metadata

Type
object

tags

Type
array

referrer_url

Type
string

utm_campaign

Type
string

utm_medium

Type
string

utm_source

Type
string

referring_subscriber_id

Type
string

type

Type
SubscriberType
Example
"regular"

X-Buttondown-Collision-Behavior

Type
string

© 2016–2024 Buttondown LLC.

TwitterDiscord GitHubLinkedInMastodonBlueskyFacebook