Create Subscriber

POST

api

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>",
  "phoneCountry": "<string>",
  "smsConsent": true,
  "status": "<string>",
  "optInMode": "<string>",
  "tags": [
    "<string>"
  ],
  "lists": [
    "<string>"
  ],
  "customAttributes": {},
  "enrollInSequences": true,
  "createdAt": "<string>",
  "duplicateStrategy": "<string>"
}
'

import requests

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

payload = {
    "email": "<string>",
    "externalId": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "phone": "<string>",
    "phoneCountry": "<string>",
    "smsConsent": True,
    "status": "<string>",
    "optInMode": "<string>",
    "tags": ["<string>"],
    "lists": ["<string>"],
    "customAttributes": {},
    "enrollInSequences": True,
    "createdAt": "<string>",
    "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>',
    phoneCountry: '<string>',
    smsConsent: true,
    status: '<string>',
    optInMode: '<string>',
    tags: ['<string>'],
    lists: ['<string>'],
    customAttributes: {},
    enrollInSequences: true,
    createdAt: '<string>',
    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>',
    'phoneCountry' => '<string>',
    'smsConsent' => true,
    'status' => '<string>',
    'optInMode' => '<string>',
    'tags' => [
        '<string>'
    ],
    'lists' => [
        '<string>'
    ],
    'customAttributes' => [
        
    ],
    'enrollInSequences' => true,
    'createdAt' => '<string>',
    '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  \"phoneCountry\": \"<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  \"createdAt\": \"<string>\",\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  \"phoneCountry\": \"<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  \"createdAt\": \"<string>\",\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  \"phoneCountry\": \"<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  \"createdAt\": \"<string>\",\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 unless phone is provided - a contact created with only a phone becomes a phone-only (SMS) contact that email sends automatically skip.

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 national format. Stored normalized to E.164 on the native phone field, not as a custom attribute. An invalid phone returns 400 VALIDATION_ERROR. Setting a phone does NOT subscribe the contact to SMS - use smsConsent for that. With no email or externalId, the phone creates or matches a phone-only (SMS) contact.

string

ISO 3166-1 alpha-2 country used to read a national-format phone, such as IT or US. Defaults to US. This is a parsing hint only: the stored phoneCountry always comes from the parsed number. Sending it without phone returns 400 VALIDATION_ERROR.

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, or to false when you supply createdAt.

string

ISO 8601 date the contact originally signed up, for importing history from another platform. See Preserving the original signup date.

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

By default a new contact’s signup date is the moment you created them. That is right for a real signup and wrong for a migration: if you import 50,000 contacts today, all 50,000 look like they joined today, and an audience like “signed up in the last 30 days” matches your entire list on day one and nobody on day 31. Pass createdAt to keep their real date:

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",
    "createdAt": "2019-03-14T09:30:00Z"
  }'

Three things to know:

It only ever moves earlier. If the contact already exists with an earlier date, yours is ignored - an earlier date is more history than we had, a later one would erase some. This holds for every duplicateStrategy.
Sequences do not run. Supplying createdAt defaults enrollInSequences to false, because you are describing the past, not a signup happening now. Pass enrollInSequences: true to override.
Only the signup date moves. The contact’s “last updated” time stays the real one, so recently-changed views still tell the truth.

Any list you add them to is joined at the same date. To import their event history too, see Trigger Event. For a whole file at once, put createdAt on each record in Create Subscriber Import.

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.

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>",
  "phoneCountry": "<string>",
  "smsConsent": true,
  "status": "<string>",
  "optInMode": "<string>",
  "tags": [
    "<string>"
  ],
  "lists": [
    "<string>"
  ],
  "customAttributes": {},
  "enrollInSequences": true,
  "createdAt": "<string>",
  "duplicateStrategy": "<string>"
}
'

import requests

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

payload = {
    "email": "<string>",
    "externalId": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "phone": "<string>",
    "phoneCountry": "<string>",
    "smsConsent": True,
    "status": "<string>",
    "optInMode": "<string>",
    "tags": ["<string>"],
    "lists": ["<string>"],
    "customAttributes": {},
    "enrollInSequences": True,
    "createdAt": "<string>",
    "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>',
    phoneCountry: '<string>',
    smsConsent: true,
    status: '<string>',
    optInMode: '<string>',
    tags: ['<string>'],
    lists: ['<string>'],
    customAttributes: {},
    enrollInSequences: true,
    createdAt: '<string>',
    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>',
    'phoneCountry' => '<string>',
    'smsConsent' => true,
    'status' => '<string>',
    'optInMode' => '<string>',
    'tags' => [
        '<string>'
    ],
    'lists' => [
        '<string>'
    ],
    'customAttributes' => [
        
    ],
    'enrollInSequences' => true,
    'createdAt' => '<string>',
    '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  \"phoneCountry\": \"<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  \"createdAt\": \"<string>\",\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  \"phoneCountry\": \"<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  \"createdAt\": \"<string>\",\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  \"phoneCountry\": \"<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  \"createdAt\": \"<string>\",\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"
}

​Request Body

​Responses

​Preserving the Original Signup Date

Double Opt-In

SMS & MMS

Request Body

Responses

Preserving the Original Signup Date