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'
tagsstring[]
listsstring[]

List IDs to add subscriber to. If not provided, subscriber is added to ALL company lists. 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
  }
}

Changes