Subscribers

Update subscriber

Changed on

Updates a subscriber's first name, last name, status, tags, or custom attributes. Setting status to unsubscribed performs the full unsubscribe workflow, including list unsubscription and sequence cancellation.

patch/subscribers/{email}

Request

  • Base URL
    https://api.sequenzy.com/api/v1
  • URL
    https://api.sequenzy.com/api/v1/subscribers/{email}
  • Auth
    HTTP bearer

Path parameters

emailstring required

URL-encoded email address

Request body

emailstring email

New delivery email. Fails with 409 if another subscriber owns it.

externalIdstring

New customer-owned external ID. Fails with 409 if another subscriber owns it.

firstNamestring

Maximum 255 Unicode characters. Excess trailing ASCII spaces are accepted as by PostgreSQL. Longer names return 400 before any changes; correct the name before retrying. Omit to keep unchanged, or send an empty string to clear; null is not accepted.

lastNamestring

Maximum 255 Unicode characters. Excess trailing ASCII spaces are accepted as by PostgreSQL. Longer names return 400 before any changes; correct the name before retrying. Omit to keep unchanged, or send an empty string to clear; null is not accepted.

timezonestring nullable

IANA timezone identifier such as America/New_York, stored as a native profile field and used for recipient-local campaign delivery. An invalid identifier returns 400 VALIDATION_ERROR. Omit to keep unchanged, or send null to clear.

phonestring nullable

Phone number in E.164 format or national format. Stored normalized to E.164. Invalid values fail with a 400 validation error. Does not affect SMS consent. Changing it resets SMS consent unless smsConsent is sent in the same request. null or "" clears the phone, except on a phone-only (SMS) contact, where clearing its only identity fails with a 400 validation error.

phoneCountrystring nullable

ISO 3166-1 alpha-2 country used to read a national-format phone, defaulting to US. A parsing hint only - the stored phoneCountry always comes from the parsed number. Sending it without phone fails with a 400 validation error.

smsConsentboolean

SMS marketing consent. true sets smsStatus to subscribed with consent source api, false sets unsubscribed, omitted leaves SMS status unchanged. Never inferred from phone presence.

status'active' | 'unsubscribed' | 'bounced' | 'complained'

Setting unsubscribed performs a full global unsubscribe. Setting complained records a company spam-complaint suppression (visible through the suppressions endpoints), then runs the same unsubscribe workflow; the subscriber then reads as unsubscribed. Repeating it is safe.

tagsstring[]
customAttributesobject

Custom attributes to update. Defaults to replacing the existing public custom-attribute map.

customAttributesStrategy'replace' | 'merge'

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

Example request

{
  "firstName": "Jane",
  "lastName": "Smith",
  "timezone": "America/New_York",
  "phone": "+15551234567",
  "phoneCountry": "IT",
  "tags": [
    "premium",
    "vip"
  ]
}

Response

Subscriber updated

successboolean

Example response

{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "user@example.com",
    "externalId": "user_123",
    "firstName": "John",
    "lastName": "Doe",
    "timezone": "America/New_York",
    "phone": "+15551234567",
    "smsStatus": "subscribed",
    "status": "active",
    "unsubscribedAt": "2026-07-15T10:00:00.000Z",
    "emailProvider": "gmail",
    "tags": [
      "premium",
      "newsletter"
    ],
    "customAttributes": {
      "plan": "pro",
      "signupSource": "website"
    },
    "phoneCountry": "US"
  }
}

Changes

  • 75ac3f76f3c3Revision changes
    • info

      added the new complained enum value to the request property

  • db3873ca3d4dRevision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status