Subscribers By External ID

GET

api

subscribers

external

curl --request GET \
  --url https://api.sequenzy.com/api/v1/subscribers/external \
  --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>",
  "tags": [
    {}
  ],
  "customAttributes": {},
  "customAttributesStrategy": "<string>"
}
'

import requests

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

payload = {
    "email": "<string>",
    "externalId": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "phone": "<string>",
    "phoneCountry": "<string>",
    "smsConsent": True,
    "status": "<string>",
    "tags": [{}],
    "customAttributes": {},
    "customAttributesStrategy": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'GET',
  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>',
    tags: [{}],
    customAttributes: {},
    customAttributesStrategy: '<string>'
  })
};

fetch('https://api.sequenzy.com/api/v1/subscribers/external', 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/external",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => '<string>',
    'externalId' => '<string>',
    'firstName' => '<string>',
    'lastName' => '<string>',
    'phone' => '<string>',
    'phoneCountry' => '<string>',
    'smsConsent' => true,
    'status' => '<string>',
    'tags' => [
        [
                
        ]
    ],
    'customAttributes' => [
        
    ],
    'customAttributesStrategy' => '<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/external"

	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  \"tags\": [\n    {}\n  ],\n  \"customAttributes\": {},\n  \"customAttributesStrategy\": \"<string>\"\n}")

	req, _ := http.NewRequest("GET", 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.get("https://api.sequenzy.com/api/v1/subscribers/external")
  .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  \"tags\": [\n    {}\n  ],\n  \"customAttributes\": {},\n  \"customAttributesStrategy\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.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  \"tags\": [\n    {}\n  ],\n  \"customAttributes\": {},\n  \"customAttributesStrategy\": \"<string>\"\n}"

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

{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "anna@example.com",
    "externalId": "user_123",
    "status": "active",
    "tags": ["customer"],
    "customAttributes": {
      "plan": "pro"
    }
  }
}

{
  "success": true,
  "deleted": true
}

{
  "success": false,
  "error": "externalId is required"
}

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

{
  "success": false,
  "error": "Subscriber not found"
}

{
  "success": false,
  "error": "Another subscriber already uses that email or externalId"
}

Use external-ID routes when your app has a stable customer, account, or user ID. Prefer the query form because it supports external IDs that contain slashes. For GET, email engagement stats and recent activity exclude detected email-security scanners and tracked brand assets by default. Subscriber notes can also use external IDs with GET or POST /api/v1/subscribers/external/notes?externalId={externalId}.

Request

string

required

Customer-owned external ID. Required for GET, PATCH, and DELETE /subscribers/external.

string

Compatibility path form for external IDs that do not contain slashes.

boolean

default:"false"

Set to true on GET requests to include detected scanner, preview, and tracked asset open/click events in emailStats and recent activity.

When machine engagement is included, open/click activity events include machine, engagementQuality, and classificationReasons fields.

string

New subscriber email when updating.

string

New external ID when updating.

string

Updated first name.

string

Updated last name.

string

Updated phone number in E.164 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. Changing the number without smsConsent resets SMS consent. null or "" clears the phone, except on a phone-only contact with no email.

string

ISO 3166-1 alpha-2 country used to read a national-format phone, such as IT or US. Defaults to US. Send it only together with phone.

SMS marketing consent. true subscribes the contact with consent source api and must only be sent with verified express written consent. false unsubscribes the contact from SMS. When omitted, SMS status stays unchanged unless phone changes, which resets consent because it belonged to the old number. Consent is never inferred from phone presence. See SMS & MMS for the full consent model.

string

Updated status: active or unsubscribed.

array

Replacement tag list.

object

Custom attributes to update. By default this replaces the existing public custom-attribute map.

string

default:"replace"

How to apply customAttributes: replace replaces the existing public custom-attribute map, while merge overwrites only the provided keys and retains unspecified existing keys.

curl "https://api.sequenzy.com/api/v1/subscribers/external?externalId=user_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X PATCH "https://api.sequenzy.com/api/v1/subscribers/external?externalId=user_123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "anna@example.com", "customAttributesStrategy": "merge", "customAttributes": {"plan": "pro"}}'

curl -X DELETE "https://api.sequenzy.com/api/v1/subscribers/external?externalId=user_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "anna@example.com",
    "externalId": "user_123",
    "status": "active",
    "tags": ["customer"],
    "customAttributes": {
      "plan": "pro"
    }
  }
}

{
  "success": true,
  "deleted": true
}

{
  "success": false,
  "error": "externalId is required"
}

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

{
  "success": false,
  "error": "Subscriber not found"
}

{
  "success": false,
  "error": "Another subscriber already uses that email or externalId"
}

Subscribers By External ID

curl --request GET \
  --url https://api.sequenzy.com/api/v1/subscribers/external \
  --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>",
  "tags": [
    {}
  ],
  "customAttributes": {},
  "customAttributesStrategy": "<string>"
}
'

import requests

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

payload = {
    "email": "<string>",
    "externalId": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "phone": "<string>",
    "phoneCountry": "<string>",
    "smsConsent": True,
    "status": "<string>",
    "tags": [{}],
    "customAttributes": {},
    "customAttributesStrategy": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'GET',
  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>',
    tags: [{}],
    customAttributes: {},
    customAttributesStrategy: '<string>'
  })
};

fetch('https://api.sequenzy.com/api/v1/subscribers/external', 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/external",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => '<string>',
    'externalId' => '<string>',
    'firstName' => '<string>',
    'lastName' => '<string>',
    'phone' => '<string>',
    'phoneCountry' => '<string>',
    'smsConsent' => true,
    'status' => '<string>',
    'tags' => [
        [
                
        ]
    ],
    'customAttributes' => [
        
    ],
    'customAttributesStrategy' => '<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/external"

	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  \"tags\": [\n    {}\n  ],\n  \"customAttributes\": {},\n  \"customAttributesStrategy\": \"<string>\"\n}")

	req, _ := http.NewRequest("GET", 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.get("https://api.sequenzy.com/api/v1/subscribers/external")
  .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  \"tags\": [\n    {}\n  ],\n  \"customAttributes\": {},\n  \"customAttributesStrategy\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.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  \"tags\": [\n    {}\n  ],\n  \"customAttributes\": {},\n  \"customAttributesStrategy\": \"<string>\"\n}"

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

{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "anna@example.com",
    "externalId": "user_123",
    "status": "active",
    "tags": ["customer"],
    "customAttributes": {
      "plan": "pro"
    }
  }
}

{
  "success": true,
  "deleted": true
}

{
  "success": false,
  "error": "externalId is required"
}

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

{
  "success": false,
  "error": "Subscriber not found"
}

{
  "success": false,
  "error": "Another subscriber already uses that email or externalId"
}

Overview

Companies

Sync Rules

Shopify

Websites

Integrations

Sender Profiles

Tracking Settings

Sending Status

Notification Preferences

Subscribers

Tags

Lists

Events

Segments

Audience Syncs

Migrations

Products

Media

Analytics

Sequences

Generation

SMS

Campaigns

Landing Pages

Emails

A/B Tests

Email Sends

Suppressions

Transactional

Templates

Widgets

Commerce

Webhooks

Team

Conversations

Subscribers By External ID

Request

Responses

​Request

​Responses

Request

Responses