Sign in
Subscribers

Create or update subscriber

Creates a new subscriber or handles existing ones based on the duplicateStrategy parameter.

Duplicate Strategies:

  • skip (default): Don't update existing subscribers
  • merge: Only fill in missing fields, never overwrite existing values
  • overwrite: Replace all fields (but never reactivate unsubscribed users)
post/subscribers

Request body

emailstring email

Required when creating a new subscriber. Optional when externalId identifies an existing subscriber.

externalIdstring

Customer-owned app/customer/user ID. Unique per company when provided.

firstNamestring
lastNamestring
status'active' | 'unsubscribed' | 'bounced'

Initial subscriber status.

optInMode'default' | 'confirmed' | 'double_opt_in'

Consent handling for this request:

  • default: obey the company double opt-in setting for new active subscribers; existing unsubscribed contacts are not sent confirmation email
  • confirmed: create or keep active immediately when you have verified consent
  • double_opt_in: send a confirmation email and keep the contact unsubscribed until they confirm
tagsstring[]
listsstring[]

List IDs to add subscriber to. If not provided, subscriber follows the workspace default lists setting. If empty array, subscriber is added to NO lists.

customAttributesobject
enrollInSequencesboolean

Whether to enroll the subscriber in matching sequences. Defaults to true for API calls.

duplicateStrategy'skip' | 'merge' | 'overwrite'

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)

Example request

{
  "email": "user@example.com",
  "externalId": "user_123",
  "firstName": "John",
  "lastName": "Doe",
  "tags": [
    "newsletter"
  ],
  "lists": [
    "list-id-1",
    "list-id-2"
  ],
  "customAttributes": {
    "plan": "free"
  }
}

Response

Subscriber created or handled based on duplicate strategy

successboolean

Example response

{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "user@example.com",
    "externalId": "user_123",
    "firstName": "John",
    "lastName": "Doe",
    "status": "active",
    "emailProvider": "gmail",
    "tags": [
      "premium",
      "newsletter"
    ],
    "customAttributes": {
      "plan": "pro",
      "signupSource": "website"
    },
    "created": true
  },
  "optIn": {
    "required": true,
    "emailQueued": true
  }
}

Changes