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": ["tag-1", "tag-2"]
} # This will succeed, and return a 201 status code.

POST /v1/subscribers {
  "email_address": "john@example.com",
  "tags": ["tag-2", "tag-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: Token $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email_address": "john@example.com", "tags": ["tag-1", "tag-2"]}'

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

Buttondown validates all incoming subscribers through the API, making it easy for you to spend less time worrying about spam and more time building your newsletter.

We can only validate based on the information you provide, though. When looking at incoming traffic, a very useful heuristic is to look at the IP address of the request: if we see, for instance, a given IP address that has submitted a lot of requests in a short period of time, we can flag that for manual review.

To help with this, you can now provide an ip_address. This will be used to determine the subscriber's location and validate their legitimacy (especially useful for folks submitting requests from a form that doesn't have CAPTCHA protection or similar anti-spam measures). You should proxy this directly from the request you receive, and if provided we'll use it rather than the IP address from which you make the API call. If it isn’t included and your API calls come from a limited set of IPs, our firewall may interpret the repeat activity from those IPs as suspicious and block the corresponding subscribers.

We rate limit this endpoint to protect against abuse and unintentional usage; the default limit is one hundred requests per hour and naturally grows over time as your newsletter accumulates reputation within Buttondown. If you've got a specific use case that requires a higher rate limit, please contact us and we'll be happy to help; if you're running into rate limiting because of an initial import of subscribers, we suggest bringing those subscribers in via a CSV instead.

You can simultaneously create a new subscriber and add a tag or tags to them by supplying the tags field in the request body. If you supply a tag that does not already exist, Buttondown will create and persist the tag for you.

Sample requests

These sample requests are autogenerated by the OpenAPI spec.

import requests

url = "https://api.buttondown.com/v1/subscribers"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "email_address": "telemachus@buttondown.email",
  "type": "regular",
  "ip_address": "127.0.0.1"
}

response = requests.request("POST", url, headers=headers, json=data)
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",
    "avatar_url": "",
    "churn_date": null,
    "email_address": "telemachus@buttondown.email",
    "gift_subscription_message": "",
    "ip_address": null,
    "last_click_date": null,
    "last_open_date": null,
    "metadata": {
        "name": "Telemachus"
    },
    "notes": "",
    "purchased_by": null,
    "purchased_message": null,
    "referral_code": "",
    "referrer_url": "",
    "risk_score": null,
    "secondary_id": 1,
    "source": "organic",
    "stripe_coupon": null,
    "stripe_customer_id": null,
    "subscriber_import_id": null,
    "tags": [],
    "transitions": [],
    "email_transitions": [],
    "type": "unactivated",
    "undeliverability_date": null,
    "undeliverability_reason": null,
    "unsubscription_date": null,
    "unsubscription_reason": "",
    "upgrade_date": null,
    "utm_campaign": "",
    "utm_medium": "",
    "utm_source": "",
    "stripe_customer": null
}

Path parameters

Consult the Filtering documentation for more information on how to filter and sort your requests.

Body parameters

All parameters are optional unless explicitly specified.

Error codes

This endpoint may return the following error codes. See the error codes reference for more details about error handling.