Buttondown Documentation
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.
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:
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.
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:
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.
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.
These sample requests are autogenerated by the OpenAPI spec.
The IDs and values referenced in these responses are fake; please only rely on these responses for overall structure.
All parameters are optional unless explicitly specified.
"telemachus@buttondown.email"
Any notes you want to attach to the subscriber. These are not publicly visible.
A structured key-value blob that you can use to store arbitrary data on the object.
The ID of the subscriber that referred this subscriber.
The IP address of the subscriber. If provided, we will use this IP address to determine the subscriber's location and validate their legitimacy.
"127.0.0.1"