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.

If you're creating subscribers from a trusted source (such as a cloud function that handles purchases from Stripe), you may want to bypass the firewall entirely for those requests. You can do this by providing a X-Buttondown-Bypass-Firewall header with a value of true:

curl -X POST https://api.buttondown.com/v1/subscribers \
  -H "X-Buttondown-Bypass-Firewall: true" \
  -H "Authorization: Token $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email_address": "john@example.com", "tags": ["purchased"]}'

This is useful when you don't have access to the subscriber's IP address (e.g. processing a webhook from a payment provider) and don't want Buttondown's firewall to flag the request as suspicious.

This header is subject to aggressive rate limiting (five requests per hour per newsletter) to prevent abuse. If you exceed this limit, the API will return a 429 status code.

We rate limit this endpoint to protect against abuse and unintentional usage; the default limit is one hundred requests per day 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.