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