Add Tag - Sequenzy

POST

api

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": {}
}
'

import requests

url = "https://api.sequenzy.com/api/v1/subscribers/tags"

payload = {
    "email": "<string>",
    "externalId": "<string>",
    "tag": "<string>",
    "customAttributes": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: '<string>',
    externalId: '<string>',
    tag: '<string>',
    customAttributes: {}
  })
};

fetch('https://api.sequenzy.com/api/v1/subscribers/tags', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sequenzy.com/api/v1/subscribers/tags",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => '<string>',
    'externalId' => '<string>',
    'tag' => '<string>',
    'customAttributes' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sequenzy.com/api/v1/subscribers/tags"

	payload := strings.NewReader("{\n  \"email\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"customAttributes\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sequenzy.com/api/v1/subscribers/tags")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"customAttributes\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sequenzy.com/api/v1/subscribers/tags")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"customAttributes\": {}\n}"

response = http.request(request)
puts response.read_body

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

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

{
  "success": false,
  "error": "Unauthorized"
}

{
  "success": false,
  "error": "Subscriber identity conflict: email and externalId point to different subscribers."
}

{
  "success": false,
  "error": "Internal server error"
}

Add a single tag to a subscriber. Creates the subscriber and/or tag if they don’t exist.

Request Body

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:

Resource	Behavior
Subscriber	Created if email doesn’t exist - `active` status, or pending confirmation when double opt-in is enabled
Tag	Created 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
  }
}

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

{
  "success": false,
  "error": "Unauthorized"
}

{
  "success": false,
  "error": "Subscriber identity conflict: email and externalId point to different subscribers."
}

{
  "success": false,
  "error": "Internal server error"
}

Response Fields

Field	Description
`subscriber.created`	`true` if subscriber was created by this request
`tag.created`	`true` if tag definition was created by this request
`optIn`	Present 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.

Add Tags (Bulk)Add multiple tags to a subscriber in one request

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": {}
}
'

import requests

url = "https://api.sequenzy.com/api/v1/subscribers/tags"

payload = {
    "email": "<string>",
    "externalId": "<string>",
    "tag": "<string>",
    "customAttributes": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: '<string>',
    externalId: '<string>',
    tag: '<string>',
    customAttributes: {}
  })
};

fetch('https://api.sequenzy.com/api/v1/subscribers/tags', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sequenzy.com/api/v1/subscribers/tags",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => '<string>',
    'externalId' => '<string>',
    'tag' => '<string>',
    'customAttributes' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sequenzy.com/api/v1/subscribers/tags"

	payload := strings.NewReader("{\n  \"email\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"customAttributes\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sequenzy.com/api/v1/subscribers/tags")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"customAttributes\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sequenzy.com/api/v1/subscribers/tags")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"tag\": \"<string>\",\n  \"customAttributes\": {}\n}"

response = http.request(request)
puts response.read_body

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

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

{
  "success": false,
  "error": "Unauthorized"
}

{
  "success": false,
  "error": "Subscriber identity conflict: email and externalId point to different subscribers."
}

{
  "success": false,
  "error": "Internal server error"
}

​Request Body

​Auto-Creation Behavior

​Double Opt-In

​Tag Normalization

​Responses

​Response Fields

​Use Cases

​Track Customer Status

​Segment by Interest

Request Body

Auto-Creation Behavior

Double Opt-In

Tag Normalization

Responses

Response Fields

Use Cases

Track Customer Status

Segment by Interest