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 -X POST https://api.buttondown.email/v1/tags

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 -X GET https://api.buttondown.email/v1/tags

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 -X GET https://api.buttondown.email/v1/tags/{pk}

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

Update Tag

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

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 -X DELETE https://api.buttondown.email/v1/tags/{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."
}