Subscribers
Create Subscriber
Create a new subscriber or update an existing one based on duplicate strategy
POST
/
api
/
v1
/
subscribers
Create Subscriber
curl --request POST \
--url https://api.sequenzy.com/api/v1/subscribers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"email": "<string>",
"externalId": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"phone": "<string>",
"smsConsent": true,
"status": "<string>",
"optInMode": "<string>",
"tags": [
"<string>"
],
"lists": [
"<string>"
],
"customAttributes": {},
"enrollInSequences": true,
"duplicateStrategy": "<string>"
}
'import requests
url = "https://api.sequenzy.com/api/v1/subscribers"
payload = {
"email": "<string>",
"externalId": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"phone": "<string>",
"smsConsent": True,
"status": "<string>",
"optInMode": "<string>",
"tags": ["<string>"],
"lists": ["<string>"],
"customAttributes": {},
"enrollInSequences": True,
"duplicateStrategy": "<string>"
}
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>',
firstName: '<string>',
lastName: '<string>',
phone: '<string>',
smsConsent: true,
status: '<string>',
optInMode: '<string>',
tags: ['<string>'],
lists: ['<string>'],
customAttributes: {},
enrollInSequences: true,
duplicateStrategy: '<string>'
})
};
fetch('https://api.sequenzy.com/api/v1/subscribers', 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",
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>',
'firstName' => '<string>',
'lastName' => '<string>',
'phone' => '<string>',
'smsConsent' => true,
'status' => '<string>',
'optInMode' => '<string>',
'tags' => [
'<string>'
],
'lists' => [
'<string>'
],
'customAttributes' => [
],
'enrollInSequences' => true,
'duplicateStrategy' => '<string>'
]),
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"
payload := strings.NewReader("{\n \"email\": \"<string>\",\n \"externalId\": \"<string>\",\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"phone\": \"<string>\",\n \"smsConsent\": true,\n \"status\": \"<string>\",\n \"optInMode\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"lists\": [\n \"<string>\"\n ],\n \"customAttributes\": {},\n \"enrollInSequences\": true,\n \"duplicateStrategy\": \"<string>\"\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")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"<string>\",\n \"externalId\": \"<string>\",\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"phone\": \"<string>\",\n \"smsConsent\": true,\n \"status\": \"<string>\",\n \"optInMode\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"lists\": [\n \"<string>\"\n ],\n \"customAttributes\": {},\n \"enrollInSequences\": true,\n \"duplicateStrategy\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sequenzy.com/api/v1/subscribers")
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 \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"phone\": \"<string>\",\n \"smsConsent\": true,\n \"status\": \"<string>\",\n \"optInMode\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"lists\": [\n \"<string>\"\n ],\n \"customAttributes\": {},\n \"enrollInSequences\": true,\n \"duplicateStrategy\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"subscriber": {
"id": "sub_abc123",
"email": "user@example.com",
"externalId": "user_123",
"firstName": "John",
"lastName": "Doe",
"phone": "+15551234567",
"smsStatus": "subscribed",
"status": "active",
"tags": ["lead", "saas.monthly"],
"createdAt": "2024-01-15T10:30:00Z",
"created": true,
"updated": false,
"skipped": false
}
}
{
"success": true,
"subscriber": {
"id": "sub_abc123",
"email": "user@example.com",
"externalId": "user_123",
"firstName": "John",
"lastName": "Doe",
"status": "unsubscribed",
"tags": [],
"createdAt": "2024-01-15T10:30:00Z",
"created": true,
"updated": false,
"skipped": false
},
"optIn": {
"required": true,
"emailQueued": true
}
}
{
"success": true,
"subscriber": {
"id": "sub_abc123",
"email": "user@example.com",
"externalId": "user_123",
"firstName": "John",
"lastName": "Doe",
"status": "active",
"tags": ["existing-tag"],
"createdAt": "2024-01-10T08:00:00Z",
"created": false,
"updated": false,
"skipped": true
}
}
{
"success": true,
"subscriber": {
"id": "sub_abc123",
"email": "user@example.com",
"firstName": "John",
"lastName": "Doe",
"status": "active",
"tags": ["existing-tag", "lead", "saas.monthly"],
"createdAt": "2024-01-10T08:00:00Z",
"created": false,
"updated": true,
"skipped": false
}
}
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid phone number. Provide a valid phone in E.164 format, e.g. +15551234567, or US national format."
}
}
{
"success": false,
"error": "Unauthorized"
}
{
"success": false,
"error": "Subscriber identity conflict: email and externalId point to different subscribers."
}
{
"success": false,
"error": "Internal server error"
}
Create a new subscriber or handle existing ones based on the
duplicateStrategy parameter.
Request Body
string
Subscriber delivery email address. Required when creating a new subscriber.
string
Your app/customer/user ID for this subscriber. It is unique within your
workspace and is trimmed without lowercasing.
string
First name
string
Last name
string
Phone number in E.164 format (
+15551234567) or US national format. Stored
normalized to E.164. An invalid phone returns 400 VALIDATION_ERROR.
Setting a phone does NOT subscribe the contact to SMS - use smsConsent for
that.boolean
SMS marketing consent.
true sets the subscriber’s SMS status to
subscribed with consent source api - only send true when you have
express written consent. false sets it to unsubscribed. Omitted leaves
SMS status unchanged. Consent is never inferred from phone presence. See
SMS & MMS for the full consent model.string
default:"active"
Status:
active, unsubscribed, or bounced.string
default:"default"
Consent mode:
default obeys your workspace double opt-in setting for new
active subscribers, confirmed creates an active subscriber immediately when
you have verified consent, and double_opt_in sends a confirmation email and
keeps the contact unsubscribed until they confirm.Omitting
optInMode follows the workspace double opt-in setting. Use
confirmed only when your app already verified consent. When confirmation is
required, Sequenzy applies requested lists and tags only after the subscriber
clicks the confirmation link. default does not send confirmation email to an
existing unsubscribed contact.string[]
Array of tag names to assign
string[]
Array of list IDs to add the subscriber to. If omitted, the subscriber follows
your workspace default lists setting. If set to an empty array
[], the
subscriber will not be added to any lists.object
Custom key-value attributes
boolean
default:"true"
Whether to enroll the subscriber in matching sequences. Defaults to
true.string
default:"skip"
How to handle existing subscribers: -
skip - Don’t update existing
subscribers (default) - merge - Only fill in missing fields, never overwrite
existing values - overwrite - Replace all fields (but never reactivate
unsubscribed users)curl -X POST "https://api.sequenzy.com/api/v1/subscribers" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"externalId": "user_123",
"firstName": "John",
"lastName": "Doe",
"phone": "+15551234567",
"smsConsent": true,
"tags": ["lead", "saas.monthly"],
"lists": ["list_abc123"],
"enrollInSequences": true,
"duplicateStrategy": "skip"
}'
Responses
{
"success": true,
"subscriber": {
"id": "sub_abc123",
"email": "user@example.com",
"externalId": "user_123",
"firstName": "John",
"lastName": "Doe",
"phone": "+15551234567",
"smsStatus": "subscribed",
"status": "active",
"tags": ["lead", "saas.monthly"],
"createdAt": "2024-01-15T10:30:00Z",
"created": true,
"updated": false,
"skipped": false
}
}
{
"success": true,
"subscriber": {
"id": "sub_abc123",
"email": "user@example.com",
"externalId": "user_123",
"firstName": "John",
"lastName": "Doe",
"status": "unsubscribed",
"tags": [],
"createdAt": "2024-01-15T10:30:00Z",
"created": true,
"updated": false,
"skipped": false
},
"optIn": {
"required": true,
"emailQueued": true
}
}
{
"success": true,
"subscriber": {
"id": "sub_abc123",
"email": "user@example.com",
"externalId": "user_123",
"firstName": "John",
"lastName": "Doe",
"status": "active",
"tags": ["existing-tag"],
"createdAt": "2024-01-10T08:00:00Z",
"created": false,
"updated": false,
"skipped": true
}
}
{
"success": true,
"subscriber": {
"id": "sub_abc123",
"email": "user@example.com",
"firstName": "John",
"lastName": "Doe",
"status": "active",
"tags": ["existing-tag", "lead", "saas.monthly"],
"createdAt": "2024-01-10T08:00:00Z",
"created": false,
"updated": true,
"skipped": false
}
}
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid phone number. Provide a valid phone in E.164 format, e.g. +15551234567, or US national format."
}
}
{
"success": false,
"error": "Unauthorized"
}
{
"success": false,
"error": "Subscriber identity conflict: email and externalId point to different subscribers."
}
{
"success": false,
"error": "Internal server error"
}
Double Opt-In
Learn how confirmation emails, pending subscribers, and signup tags work.
SMS & MMS
Learn how SMS consent, quiet hours, and message credits work.
Previous
Create Subscriber ImportQueue an asynchronous import of up to 5,000 full subscriber records
Next
⌘I
Create Subscriber
curl --request POST \
--url https://api.sequenzy.com/api/v1/subscribers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"email": "<string>",
"externalId": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"phone": "<string>",
"smsConsent": true,
"status": "<string>",
"optInMode": "<string>",
"tags": [
"<string>"
],
"lists": [
"<string>"
],
"customAttributes": {},
"enrollInSequences": true,
"duplicateStrategy": "<string>"
}
'import requests
url = "https://api.sequenzy.com/api/v1/subscribers"
payload = {
"email": "<string>",
"externalId": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"phone": "<string>",
"smsConsent": True,
"status": "<string>",
"optInMode": "<string>",
"tags": ["<string>"],
"lists": ["<string>"],
"customAttributes": {},
"enrollInSequences": True,
"duplicateStrategy": "<string>"
}
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>',
firstName: '<string>',
lastName: '<string>',
phone: '<string>',
smsConsent: true,
status: '<string>',
optInMode: '<string>',
tags: ['<string>'],
lists: ['<string>'],
customAttributes: {},
enrollInSequences: true,
duplicateStrategy: '<string>'
})
};
fetch('https://api.sequenzy.com/api/v1/subscribers', 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",
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>',
'firstName' => '<string>',
'lastName' => '<string>',
'phone' => '<string>',
'smsConsent' => true,
'status' => '<string>',
'optInMode' => '<string>',
'tags' => [
'<string>'
],
'lists' => [
'<string>'
],
'customAttributes' => [
],
'enrollInSequences' => true,
'duplicateStrategy' => '<string>'
]),
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"
payload := strings.NewReader("{\n \"email\": \"<string>\",\n \"externalId\": \"<string>\",\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"phone\": \"<string>\",\n \"smsConsent\": true,\n \"status\": \"<string>\",\n \"optInMode\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"lists\": [\n \"<string>\"\n ],\n \"customAttributes\": {},\n \"enrollInSequences\": true,\n \"duplicateStrategy\": \"<string>\"\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")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"<string>\",\n \"externalId\": \"<string>\",\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"phone\": \"<string>\",\n \"smsConsent\": true,\n \"status\": \"<string>\",\n \"optInMode\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"lists\": [\n \"<string>\"\n ],\n \"customAttributes\": {},\n \"enrollInSequences\": true,\n \"duplicateStrategy\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sequenzy.com/api/v1/subscribers")
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 \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"phone\": \"<string>\",\n \"smsConsent\": true,\n \"status\": \"<string>\",\n \"optInMode\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"lists\": [\n \"<string>\"\n ],\n \"customAttributes\": {},\n \"enrollInSequences\": true,\n \"duplicateStrategy\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"subscriber": {
"id": "sub_abc123",
"email": "user@example.com",
"externalId": "user_123",
"firstName": "John",
"lastName": "Doe",
"phone": "+15551234567",
"smsStatus": "subscribed",
"status": "active",
"tags": ["lead", "saas.monthly"],
"createdAt": "2024-01-15T10:30:00Z",
"created": true,
"updated": false,
"skipped": false
}
}
{
"success": true,
"subscriber": {
"id": "sub_abc123",
"email": "user@example.com",
"externalId": "user_123",
"firstName": "John",
"lastName": "Doe",
"status": "unsubscribed",
"tags": [],
"createdAt": "2024-01-15T10:30:00Z",
"created": true,
"updated": false,
"skipped": false
},
"optIn": {
"required": true,
"emailQueued": true
}
}
{
"success": true,
"subscriber": {
"id": "sub_abc123",
"email": "user@example.com",
"externalId": "user_123",
"firstName": "John",
"lastName": "Doe",
"status": "active",
"tags": ["existing-tag"],
"createdAt": "2024-01-10T08:00:00Z",
"created": false,
"updated": false,
"skipped": true
}
}
{
"success": true,
"subscriber": {
"id": "sub_abc123",
"email": "user@example.com",
"firstName": "John",
"lastName": "Doe",
"status": "active",
"tags": ["existing-tag", "lead", "saas.monthly"],
"createdAt": "2024-01-10T08:00:00Z",
"created": false,
"updated": true,
"skipped": false
}
}
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid phone number. Provide a valid phone in E.164 format, e.g. +15551234567, or US national format."
}
}
{
"success": false,
"error": "Unauthorized"
}
{
"success": false,
"error": "Subscriber identity conflict: email and externalId point to different subscribers."
}
{
"success": false,
"error": "Internal server error"
}