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."
}
409Conflict
{}

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."
}
409Conflict
{}

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."
}
409Conflict
{}

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."
}
409Conflict
{}

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."
}
409Conflict
{}