Skip to main content
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>",
  "status": "<string>",
  "optInMode": "<string>",
  "tags": [
    "<string>"
  ],
  "lists": [
    "<string>"
  ],
  "customAttributes": {},
  "enrollInSequences": true,
  "duplicateStrategy": "<string>"
}
'
{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "user@example.com",
    "externalId": "user_123",
    "firstName": "John",
    "lastName": "Doe",
    "status": "active",
    "tags": ["lead", "saas.monthly"],
    "createdAt": "2024-01-15T10:30:00Z",
    "created": true,
    "updated": false,
    "skipped": false
  }
}
Create a new subscriber or handle existing ones based on the duplicateStrategy parameter.

​
Request Body

​
email
string
Subscriber delivery email address. Required when creating a new subscriber.
​
externalId
string
Your app/customer/user ID for this subscriber. It is unique within your workspace and is trimmed without lowercasing.
​
firstName
string
First name
​
lastName
string
Last name
​
status
string
default:"active"
Status: active, unsubscribed, or bounced.
​
optInMode
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.
​
tags
string[]
Array of tag names to assign
​
lists
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.
​
customAttributes
object
Custom key-value attributes
​
enrollInSequences
boolean
default:"true"
Whether to enroll the subscriber in matching sequences. Defaults to true.
​
duplicateStrategy
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",
    "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",
    "status": "active",
    "tags": ["lead", "saas.monthly"],
    "createdAt": "2024-01-15T10:30:00Z",
    "created": true,
    "updated": false,
    "skipped": false
  }
}

Double Opt-In

Learn how confirmation emails, pending subscribers, and signup tags work.