Log in or sign up for an account

Newsletter

You will likely not need to interact with your newsletter settings programmatically, but if you do, this is the endpoint for you. You can create, update, and list newsletters via the API; this is ideal for integrating with Buttondown as a headless email or newsletter provider (e.g. for a SaaS product.)

Basic newsletter

{
    "api_key": "7f819f8f-8220-4dcd-b7e3-37c81ead8b7a",
    "creation_date": "2019-08-24T14:15:22Z",
    "description": "I write about corgis and Python and lifting and all sorts of stuff!",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "Justin's neat newsletter",
    "username": "jmduke",
    "footer": "Thanks, as always, for reading!",
    "header": "Howdy, gang!",
    "tint_color": "#0069FF",
    "from_name": "Justin Duke"
}
fieldtypedescription
idstring
usernamestring
namestring
descriptionstring
creation_datestring
api_keystring

List Newsletters

$ curl -X GET https://api.buttondown.email/v1/newsletters

Responses

StatusDescriptionSample Response
200OK
{
    "results": [
        {
            "api_key": "7f819f8f-8220-4dcd-b7e3-37c81ead8b7a",
            "creation_date": "2019-08-24T14:15:22Z",
            "description": "I write about corgis and Python and lifting and all sorts of stuff!",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "name": "Justin's neat newsletter",
            "username": "jmduke",
            "footer": "Thanks, as always, for reading!",
            "header": "Howdy, gang!",
            "tint_color": "#0069FF",
            "from_name": "Justin Duke"
        }
    ],
    "count": 1
}
400Bad Request
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
403Forbidden
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

Create Newsletter

$ curl -X POST https://api.buttondown.email/v1/newsletters

Parameters

parametertypedescriptionoptional
usernamestring
namestring
descriptionstring
tint_colorstring
from_namestring
headerstring
footerstring

Responses

StatusDescriptionSample Response
201Created
{
    "api_key": "7f819f8f-8220-4dcd-b7e3-37c81ead8b7a",
    "creation_date": "2019-08-24T14:15:22Z",
    "description": "I write about corgis and Python and lifting and all sorts of stuff!",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "Justin's neat newsletter",
    "username": "jmduke",
    "footer": "Thanks, as always, for reading!",
    "header": "Howdy, gang!",
    "tint_color": "#0069FF",
    "from_name": "Justin Duke"
}
400Bad Request
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
403Forbidden
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

Error codes

typeidentifierdescription
Username already exists
username_already_existsA newsletter already exists with that username

Update Newsletter

$ curl -X PATCH https://api.buttondown.email/v1/newsletters/{pk}

Parameters

parametertypedescriptionoptional
usernamestring
namestring
descriptionstring
tint_colorstring
from_namestring
headerstring
footerstring

Responses

StatusDescriptionSample Response
200OK
{
    "api_key": "7f819f8f-8220-4dcd-b7e3-37c81ead8b7a",
    "creation_date": "2019-08-24T14:15:22Z",
    "description": "I write about corgis and Python and lifting and all sorts of stuff!",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "Justin's neat newsletter",
    "username": "jmduke",
    "footer": "Thanks, as always, for reading!",
    "header": "Howdy, gang!",
    "tint_color": "#0069FF",
    "from_name": "Justin Duke"
}
400Bad Request
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
403Forbidden
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

Delete Newsletter

$ curl -X DELETE https://api.buttondown.email/v1/newsletters/{pk}

Responses

StatusDescriptionSample Response
204No Content
{}
403Forbidden
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}
404Not Found
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}