Tags
Add Tags to Many Subscribers
Add tags to up to 500 existing subscribers in one request
POST
/
api
/
v1
/
subscribers
/
bulk
/
tags
/
add
Add Tags to Many Subscribers
curl --request POST \
--url https://api.sequenzy.com/api/v1/subscribers/bulk/tags/add \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"tags": [
"<string>"
],
"emails": [
"<string>"
],
"externalIds": [
"<string>"
],
"subscriberIds": [
"<string>"
],
"triggerAutomations": true
}
'import requests
url = "https://api.sequenzy.com/api/v1/subscribers/bulk/tags/add"
payload = {
"tags": ["<string>"],
"emails": ["<string>"],
"externalIds": ["<string>"],
"subscriberIds": ["<string>"],
"triggerAutomations": True
}
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({
tags: ['<string>'],
emails: ['<string>'],
externalIds: ['<string>'],
subscriberIds: ['<string>'],
triggerAutomations: true
})
};
fetch('https://api.sequenzy.com/api/v1/subscribers/bulk/tags/add', 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/bulk/tags/add",
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([
'tags' => [
'<string>'
],
'emails' => [
'<string>'
],
'externalIds' => [
'<string>'
],
'subscriberIds' => [
'<string>'
],
'triggerAutomations' => true
]),
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/bulk/tags/add"
payload := strings.NewReader("{\n \"tags\": [\n \"<string>\"\n ],\n \"emails\": [\n \"<string>\"\n ],\n \"externalIds\": [\n \"<string>\"\n ],\n \"subscriberIds\": [\n \"<string>\"\n ],\n \"triggerAutomations\": true\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/bulk/tags/add")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"tags\": [\n \"<string>\"\n ],\n \"emails\": [\n \"<string>\"\n ],\n \"externalIds\": [\n \"<string>\"\n ],\n \"subscriberIds\": [\n \"<string>\"\n ],\n \"triggerAutomations\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sequenzy.com/api/v1/subscribers/bulk/tags/add")
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 \"tags\": [\n \"<string>\"\n ],\n \"emails\": [\n \"<string>\"\n ],\n \"externalIds\": [\n \"<string>\"\n ],\n \"subscriberIds\": [\n \"<string>\"\n ],\n \"triggerAutomations\": true\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"tags": ["derived-churn-risk"],
"requested": 3,
"matched": 2,
"updated": 2,
"unchanged": 0,
"failed": 0,
"notFound": {
"emails": ["ghost@example.com"],
"externalIds": [],
"subscriberIds": []
},
"failures": [],
"triggeredAutomations": false,
"message": "Tagged 2 subscribers (0 already in the target state, 0 failed)."
}
{
"success": false,
"error": "A maximum of 500 subscribers can be tagged per request. Split the request into smaller batches."
}
{
"success": false,
"error": "Unauthorized"
}
{
"success": false,
"error": "triggerAutomations requires the automations:trigger scope. Omit it to reconcile tags without enrolling contacts in sequences."
}
{
"success": false,
"error": "Internal server error"
}
Add Tags to Many Subscribers
Add one or more tags to up to 500 existing subscribers in a single request. This endpoint is built for reconciling historical or derived tags, so it behaves differently from the single-subscriber Add Tag endpoint in two important ways:- It never creates contacts. Identifiers that do not match an existing subscriber come back in
notFound, so a typo in a 3,000-row reconciliation cannot create 3,000 phantom contacts. - Tag automations are skipped by default. Set
triggerAutomationstotrueonly when you actually want these contacts enrolled intag_addedsequences.
emails, externalIds, subscriberIds, or any combination. All identifier lists together must total at most 500 entries; split larger backlogs into batches.
Request
string[]
required
Tag names to add to every matched subscriber, up to 25 per request. Names are
normalized (lowercase, hyphens) the same way as everywhere else in Sequenzy.
string[]
Subscriber emails to tag.
string[]
Your app/customer/user IDs to tag.
string[]
Sequenzy subscriber IDs to tag.
boolean
Whether
tag_added sequences may enroll these contacts. Defaults to false.
Requires the automations:trigger scope.curl -X POST "https://api.sequenzy.com/api/v1/subscribers/bulk/tags/add" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tags": ["derived-churn-risk"],
"emails": ["one@example.com", "two@example.com"]
}'
Responses
{
"success": true,
"tags": ["derived-churn-risk"],
"requested": 3,
"matched": 2,
"updated": 2,
"unchanged": 0,
"failed": 0,
"notFound": {
"emails": ["ghost@example.com"],
"externalIds": [],
"subscriberIds": []
},
"failures": [],
"triggeredAutomations": false,
"message": "Tagged 2 subscribers (0 already in the target state, 0 failed)."
}
{
"success": false,
"error": "A maximum of 500 subscribers can be tagged per request. Split the request into smaller batches."
}
{
"success": false,
"error": "Unauthorized"
}
{
"success": false,
"error": "triggerAutomations requires the automations:trigger scope. Omit it to reconcile tags without enrolling contacts in sequences."
}
{
"success": false,
"error": "Internal server error"
}
Response Fields
| Field | Description |
|---|---|
requested | Identifiers you supplied |
matched | Existing subscribers those identifiers resolved to |
updated | Subscribers whose tags actually changed |
unchanged | Subscribers that already carried every tag |
failed | Subscribers whose update failed; details in failures (max 50) |
notFound | Identifiers that did not resolve, grouped by kind. Not created. |
Use Add Tag or Add Tags
(Bulk) when you want a single
contact created on the fly. Use this endpoint when the contacts already exist
and you are reconciling many of them at once.
Previous
Remove Tags from Many SubscribersRemove tags from up to 500 existing subscribers in one request
Next
⌘I
Add Tags to Many Subscribers
curl --request POST \
--url https://api.sequenzy.com/api/v1/subscribers/bulk/tags/add \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"tags": [
"<string>"
],
"emails": [
"<string>"
],
"externalIds": [
"<string>"
],
"subscriberIds": [
"<string>"
],
"triggerAutomations": true
}
'import requests
url = "https://api.sequenzy.com/api/v1/subscribers/bulk/tags/add"
payload = {
"tags": ["<string>"],
"emails": ["<string>"],
"externalIds": ["<string>"],
"subscriberIds": ["<string>"],
"triggerAutomations": True
}
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({
tags: ['<string>'],
emails: ['<string>'],
externalIds: ['<string>'],
subscriberIds: ['<string>'],
triggerAutomations: true
})
};
fetch('https://api.sequenzy.com/api/v1/subscribers/bulk/tags/add', 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/bulk/tags/add",
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([
'tags' => [
'<string>'
],
'emails' => [
'<string>'
],
'externalIds' => [
'<string>'
],
'subscriberIds' => [
'<string>'
],
'triggerAutomations' => true
]),
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/bulk/tags/add"
payload := strings.NewReader("{\n \"tags\": [\n \"<string>\"\n ],\n \"emails\": [\n \"<string>\"\n ],\n \"externalIds\": [\n \"<string>\"\n ],\n \"subscriberIds\": [\n \"<string>\"\n ],\n \"triggerAutomations\": true\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/bulk/tags/add")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"tags\": [\n \"<string>\"\n ],\n \"emails\": [\n \"<string>\"\n ],\n \"externalIds\": [\n \"<string>\"\n ],\n \"subscriberIds\": [\n \"<string>\"\n ],\n \"triggerAutomations\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sequenzy.com/api/v1/subscribers/bulk/tags/add")
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 \"tags\": [\n \"<string>\"\n ],\n \"emails\": [\n \"<string>\"\n ],\n \"externalIds\": [\n \"<string>\"\n ],\n \"subscriberIds\": [\n \"<string>\"\n ],\n \"triggerAutomations\": true\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"tags": ["derived-churn-risk"],
"requested": 3,
"matched": 2,
"updated": 2,
"unchanged": 0,
"failed": 0,
"notFound": {
"emails": ["ghost@example.com"],
"externalIds": [],
"subscriberIds": []
},
"failures": [],
"triggeredAutomations": false,
"message": "Tagged 2 subscribers (0 already in the target state, 0 failed)."
}
{
"success": false,
"error": "A maximum of 500 subscribers can be tagged per request. Split the request into smaller batches."
}
{
"success": false,
"error": "Unauthorized"
}
{
"success": false,
"error": "triggerAutomations requires the automations:trigger scope. Omit it to reconcile tags without enrolling contacts in sequences."
}
{
"success": false,
"error": "Internal server error"
}