Skip to main content
POST
/
api
/
v1
/
subscribers
/
tags
Add Tag
curl --request POST \
  --url https://api.sequenzy.com/api/v1/subscribers/tags \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "externalId": "<string>",
  "tag": "<string>",
  "customAttributes": {}
}
'
{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "user@example.com",
    "externalId": "user_123",
    "tags": ["customer"],
    "created": false
  },
  "tag": {
    "id": "tag_xyz789",
    "name": "customer",
    "created": false
  }
}
Add a single tag to a subscriber. Creates the subscriber and/or tag if they don’t exist.

​
Request Body

​
email
string
Subscriber delivery email address. Required when creating a new subscriber.
​
externalId
string
Your app/customer/user ID for this subscriber. You can tag with only externalId when the subscriber already exists.
​
tag
string
required
Tag name to add. Will be normalized (lowercase, hyphens).
​
customAttributes
object
Custom attributes to set on the subscriber.
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "externalId": "user_123",
    "tag": "customer"
  }'

​
Auto-Creation Behavior

This endpoint automatically creates resources if they don’t exist:
ResourceBehavior
SubscriberCreated if email doesn’t exist - active status, or pending confirmation when double opt-in is enabled
TagCreated and normalized if tag name doesn’t exist
This makes integration seamless—you don’t need to pre-create anything.

​
Double Opt-In

When the workspace has double opt-in enabled and this request creates a brand-new subscriber, the subscriber is stored pending confirmation and the confirmation email is queued. The tag is still applied immediately, but tag automations wait at their trigger step until the subscriber confirms. The response then includes an optIn object.

​
Tag Normalization

Tags are automatically normalized when added: 
"Pro Customer" → "pro-customer"
"VIP_User"     → "vip-user"
"Newsletter!"  → "newsletter"

​
Responses

{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "user@example.com",
    "externalId": "user_123",
    "tags": ["customer"],
    "created": false
  },
  "tag": {
    "id": "tag_xyz789",
    "name": "customer",
    "created": false
  }
}

​
Response Fields

FieldDescription
subscriber.createdtrue if subscriber was created by this request
tag.createdtrue if tag definition was created by this request
optInPresent when the new subscriber requires double opt-in confirmation before becoming active

​
Use Cases

​
Track Customer Status

# When user purchases
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "buyer@example.com",
    "tag": "customer",
    "customAttributes": {
      "purchaseDate": "2024-01-15",
      "plan": "pro"
    }
  }'

​
Segment by Interest

# When user shows interest in a topic
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "reader@example.com",
    "tag": "interested-ai"
  }'
Adding a tag can trigger automations. If you have a sequence set to start when the tag is added, it will begin automatically.