Tags allow you to organize and segment your subscribers based on their interests, behaviors, or characteristics. They’re essential for targeted email campaigns and subscriber management.

List tags

Returns a list of tags for your account.

Endpoint

GET /v3/tags

Parameters

api_key
string
required
Your account API key
curl https://api.convertkit.com/v3/tags?api_key=<your_public_api_key>

Create a tag

Create one or multiple tags for your account.

Endpoint

POST /v3/tags

Parameters

api_key
string
required
Your API key
tag
object|array
required
A JSON object or an array of JSON objects that includes the tag name. Each object should contain:
  • name (required): The name of the tag
curl -X POST https://api.convertkit.com/v3/tags\
     -H 'Content-Type: application/json'\
     -d '{ "api_secret": "<your_secret_api_key>",
           "tag": {
             "name": "Example Tag"
           } }'

Tag a subscriber

Tags are handled as subscriptions. Subscribe an email address to a tag to have that tag applied to the subscriber with that email address.

Endpoint

POST /v3/tags/#{tag_id}/subscribe

Parameters

api_secret
string
required
Your API secret key
tag_id
integer
required
The ID of the tag you want to apply
email
string
required
Subscriber email address
first_name
string
Subscriber first name
fields
object
Object of key/value pairs for custom field(s). The custom field(s) must exist before you can use it here.
tags
array
Array of tag ids to subscribe to

Deprecated Parameters

courses
array
Array of sequence ids to subscribe to. You should add the subscriber to the sequence directly.
forms
array
Array of form ids to subscribe to. You should add the subscriber to the form directly.
name
string
Subscriber first name. You should prefer using first_name listed above.
curl -X POST https://api.convertkit.com/v3/tags/<tag_id>/subscribe\
     -H "Content-Type: application/json; charset=utf-8"\
     -d '{ 
            "api_secret": "<your_secret_api_key>",
            "email": "[email protected]"
         }'

Remove tag from a subscriber

Remove a specific tag from a subscriber by subscriber ID.

Endpoint

DELETE /v3/subscribers/#{subscriber_id}/tags/#{tag_id}

Parameters

api_secret
string
required
Your API secret key
subscriber_id
integer
required
The ID of the subscriber
tag_id
integer
required
The ID of the tag to remove
curl -X DELETE https://api.convertkit.com/v3/subscribers/<subscriber_id>/tags/<tag_id>?api_secret=<your_secret_api_key>

Remove tag from a subscriber by email

Remove a specific tag from a subscriber by email address.

Endpoint

POST /v3/tags/#{tag_id}/unsubscribe

Parameters

api_secret
string
required
Your API secret key
tag_id
integer
required
The ID of the tag to remove
email
string
required
Subscriber email address
curl -X POST https://api.convertkit.com/v3/tags/<tag_id>/unsubscribe\
    -H "Content-Type: application/json; charset=utf-8"\
    -d '{ 
          "api_secret": "<your_secret_api_key>",
          "email": "[email protected]"
        }'

List subscriptions to a tag

List subscriptions to a tag including subscriber data.

Endpoint

GET /v3/tags/#{tag_id}/subscriptions

Parameters

api_secret
string
required
Your API secret key
tag_id
integer
required
The ID of the tag you want to retrieve subscriptions for
sort_order
string
Sort order for results (asc or desc). asc to list subscribers added oldest to newest, desc to list subscribers added newest to oldest. Default is asc.
subscriber_state
string
Filter by subscriber state (active or cancelled). Receive only active subscribers or cancelled subscribers.
page
string
The page of results being requested. Default value is 1. Each page of results will contain up to 50 subscriptions.
curl https://api.convertkit.com/v3/tags/<tag_id>/subscriptions?api_secret=<your_secret_api_key>