Log in or sign up for an account

Tag

Tags are a way to organize your subscribers. You can create, update, and delete tags via the API. You can also list all tags for a given newsletter.

Tags don't have any strict functionality on their own, but you can send emails to subscribers with a given tag (or to all subscribers without a given tag.)

Basic tag

{
    "color": "string",
    "creation_date": "2019-08-24T14:15:22Z",
    "description": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string"
}
fieldtypedescription
idstring
namestring
colorstring
descriptionstring
secondary_idinteger
creation_datestring

Create Tag

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}


BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/tags"


response = requests.post(f"{BASE_URL}{ENDPOINT}", headers=headers)

Parameters

parametertypedescriptionoptional
namestring
colorstring
descriptionstring

Responses

StatusDescriptionSample Response
201Created
{
    "color": "string",
    "creation_date": "2019-08-24T14:15:22Z",
    "description": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string"
}
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."
}

List Tags

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}


BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/tags"


response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)

Responses

StatusDescriptionSample Response
200OK
{
    "results": [
        {
            "color": "string",
            "creation_date": "2019-08-24T14:15:22Z",
            "description": "string",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "name": "string"
        }
    ],
    "count": 1
}
403Forbidden
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

Retrieve Tag

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}


BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/tags/{pk}"


response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)

Responses

StatusDescriptionSample Response
200OK
{
    "color": "string",
    "creation_date": "2019-08-24T14:15:22Z",
    "description": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string"
}
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."
}

Update Tag

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}


BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/tags/{pk}"


response = requests.patch(f"{BASE_URL}{ENDPOINT}", headers=headers)

Parameters

parametertypedescriptionoptional
namestring
colorstring
descriptionstring
secondary_idinteger

Responses

StatusDescriptionSample Response
200OK
{
    "color": "string",
    "creation_date": "2019-08-24T14:15:22Z",
    "description": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string"
}
400Bad Request
{
    "code": "something_went_wrong",
    "detail": "Your call is very important to us."
}

Error codes

typeidentifierdescription
Name already exists
name_already_existsThe name of the tag already exists

Delete Tag

curl
python
ruby
typescript
Copy to clipboard
import requests
headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}


BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/tags/{pk}"


response = requests.delete(f"{BASE_URL}{ENDPOINT}", headers=headers)

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."
}