Add Tags (Bulk) - Sequenzy

POST

api

subscribers

tags

bulk

Add Tags (Bulk)

curl --request POST \
  --url https://api.sequenzy.com/api/v1/subscribers/tags/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "externalId": "<string>",
  "tags": [
    "<string>"
  ],
  "customAttributes": {}
}
'

import requests

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

payload = {
    "email": "<string>",
    "externalId": "<string>",
    "tags": ["<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>',
    tags: ['<string>'],
    customAttributes: {}
  })
};

fetch('https://api.sequenzy.com/api/v1/subscribers/tags/bulk', 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/bulk",
  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>',
    'tags' => [
        '<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/bulk"

	payload := strings.NewReader("{\n  \"email\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\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/bulk")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"customAttributes\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"tags\": [\n    \"<string>\"\n  ],\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", "newsletter", "pro-plan"],
    "created": false
  },
  "tags": {
    "added": ["customer", "newsletter", "pro-plan"],
    "created": ["pro-plan"]
  }
}

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

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

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

Add multiple tags to a subscriber in one request. Creates the subscriber and/or tags if they don’t exist.

Request Body

string

Subscriber delivery email address. Required when creating a new subscriber.

string

Your app/customer/user ID for this subscriber. You can add tags with only externalId when the subscriber already exists.

string[]

required

Array of tag names to add

object

Custom attributes to set on the subscriber.

curl -X POST "https://api.sequenzy.com/api/v1/subscribers/tags/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "externalId": "user_123",
    "tags": ["customer", "newsletter", "pro-plan"]
  }'

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
Tags	Each tag created and normalized if it doesn’t exist

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 tags are still applied immediately, but tag automations wait at their trigger step until the subscriber confirms. The response then includes an optIn object.

Responses

{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "user@example.com",
    "externalId": "user_123",
    "tags": ["customer", "newsletter", "pro-plan"],
    "created": false
  },
  "tags": {
    "added": ["customer", "newsletter", "pro-plan"],
    "created": ["pro-plan"]
  }
}

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

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

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

Response Fields

Field	Description
`subscriber.created`	`true` if subscriber was created by this request
`tags.added`	All tags now on the subscriber from this request
`tags.created`	Tags that were newly created (didn’t exist before)
`optIn`	Present when the new subscriber requires double opt-in confirmation before becoming active

Use Cases

New Customer Onboarding

# Tag with multiple attributes at once
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/tags/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new-customer@example.com",
    "tags": ["customer", "onboarding", "2024-cohort", "source-organic"],
    "customAttributes": {
      "plan": "pro",
      "signupDate": "2024-01-15"
    }
  }'

Update Segments

# Batch update subscriber segments
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/tags/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "tags": ["enterprise", "high-value", "priority-support"]
  }'

Tags are normalized (lowercase, hyphens) before being added. The tags.created array shows which tag definitions were newly created by this request.

Remove TagRemove a tag from a subscriber

Add Tags (Bulk)

curl --request POST \
  --url https://api.sequenzy.com/api/v1/subscribers/tags/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "externalId": "<string>",
  "tags": [
    "<string>"
  ],
  "customAttributes": {}
}
'

import requests

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

payload = {
    "email": "<string>",
    "externalId": "<string>",
    "tags": ["<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>',
    tags: ['<string>'],
    customAttributes: {}
  })
};

fetch('https://api.sequenzy.com/api/v1/subscribers/tags/bulk', 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/bulk",
  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>',
    'tags' => [
        '<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/bulk"

	payload := strings.NewReader("{\n  \"email\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\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/bulk")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"customAttributes\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"tags\": [\n    \"<string>\"\n  ],\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", "newsletter", "pro-plan"],
    "created": false
  },
  "tags": {
    "added": ["customer", "newsletter", "pro-plan"],
    "created": ["pro-plan"]
  }
}

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

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

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

​Request Body

​Auto-Creation Behavior

​Double Opt-In

​Responses

​Response Fields

​Use Cases

​New Customer Onboarding

​Update Segments

Request Body

Auto-Creation Behavior

Double Opt-In

Responses

Response Fields

Use Cases

New Customer Onboarding

Update Segments