Creating a subscriber

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.

By default, Buttondown tries to preserve existing subscriber data, even when you create a new subscriber with the same email address.

Consider the following example (of a pseudocode request), where we attempt to create the same subscriber twice, with different tags:

POST /v1/subscribers {
  "email_address": "john@example.com",
  "tags": ["newsletter-1", "newsletter-2"]
} # This will succeed, and return a 201 status code.

POST /v1/subscribers {
  "email_address": "john@example.com",
  "tags": ["newsletter-2", "newsletter-3"]
} # This will return a 400 status code, and the subscriber will not be created.

Here, Buttondown intentionally rejects the second request, because it would overwrite the existing subscriber's data.

Similarly, imagine that you create a subscriber with a type of regular. Time passes — the subscriber unsubscribes — and then they decide they want to re-subscribe.

POST /v1/subscribers {
  "email_address": "john@example.com",
  "type": "regular"
} # This will succeed, and return a 201 status code.

# ... time passes ...

POST /v1/subscribers {
  "email_address": "john@example.com",
  "type": "regular"
} # This will _fail_, and return a 400 status code.

Again, Buttondown intentionally rejects the second request, because it would overwrite the existing subscriber's data and any history (such as emails they engaged with, surveys they completed, etc.).

The right way to model both of these scenarios would be to update the existing subscriber, rather than creating a new one altogether.

However, updating a subscriber is not necessarily feasible for all integrations. If you're looking for behavior more akin to an upsert, you can provide a X-Buttondown-Collision-Behavior header of overwrite or add in the request header:

curl -X POST https://api.buttondown.com/v1/subscribers \
  -H "X-Buttondown-Collision-Behavior: overwrite" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email_address": "john@example.com", "tags": ["newsletter-1", "newsletter-2"]}'

curl -X POST https://api.buttondown.com/v1/subscribers \
  -H "X-Buttondown-Collision-Behavior: overwrite" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email_address": "john@example.com", "tags": ["newsletter-2", "newsletter-3"]}'

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,
    "upgrade_date": null,
    "unsubscription_reason": "",
    "transitions": [],
    "ip_address": null,
    "last_open_date": null,
    "last_click_date": null,
    "stripe_customer_id": null,
    "subscriber_import_id": null,
    "stripe_customer": null
}

Body parameters

All parameters are optional unless explicitly specified.