Lists

Subscribe to email lists (authenticated)

POST https://demo.notifuse.com/api/lists.subscribe

Subscribe a contact to one or more email lists. This is an authenticated endpoint that requires a bearer token.

Unlike the public /subscribe endpoint, this endpoint can subscribe contacts to any list (public or private) as long as the authenticated user has write permission on lists.

Note: Double opt-in is bypassed for authenticated requests. Contacts are immediately set to active status regardless of the list's double opt-in setting. This allows administrators to manually add contacts without requiring email confirmation.

Authorizations

Authorization string header required

Bearer authentication header of the form Bearer <token>, where <token> is your API key.

Body application/json

workspace_id string required

The ID of the workspace

Example ws_1234567890
contact object required
Show 37 child attributes Hide 37 child attributes
email string<email> required

Email address of the contact

Example user@example.com
email_hmac string

HMAC of the email for authenticated subscription (optional)

Example a1b2c3d4e5f6...
external_id string | null

Optional identifier for the contact in your own system. Not unique — contacts are identified by email address.

Example user_12345
timezone string | null

Timezone of the contact

Example America/New_York
language string | null

Preferred language of the contact

Example en-US
first_name string | null

First name of the contact

Example John
last_name string | null

Last name of the contact

Example Doe
full_name string | null

Full name of the contact (for systems that don't have separate first/last names)

Example John Doe
phone string | null

Phone number of the contact

Example +15551234567
address_line_1 string | null

First line of address

Example 123 Main St
address_line_2 string | null

Second line of address

Example Apt 4B
country string | null

Country of the contact

Example US
postcode string | null

Postal code

Example 10001
state string | null

State or province

Example NY
job_title string | null

Job title of the contact

Example Software Engineer
tracking_opens_consent string

The visitor's choice about open tracking, for example from a checkbox on your form. Recorded with source subscribe_form on a public request.

Options granted, denied
tracking_clicks_consent string

The visitor's choice about click tracking, recorded like tracking_opens_consent.

Options granted, denied
custom_string_1 string | null

Custom string field 1

Example Premium tier
custom_string_2 string | null

Custom string field 2

custom_string_3 string | null

Custom string field 3

custom_string_4 string | null

Custom string field 4

custom_string_5 string | null

Custom string field 5

custom_number_1 number<float> | null

Custom number field 1

Example 42
custom_number_2 number<float> | null

Custom number field 2

custom_number_3 number<float> | null

Custom number field 3

custom_number_4 number<float> | null

Custom number field 4

custom_number_5 number<float> | null

Custom number field 5

custom_datetime_1 string<date-time> | null

Custom datetime field 1

Example 2023-06-01T09:00:00Z
custom_datetime_2 string<date-time> | null

Custom datetime field 2

custom_datetime_3 string<date-time> | null

Custom datetime field 3

custom_datetime_4 string<date-time> | null

Custom datetime field 4

custom_datetime_5 string<date-time> | null

Custom datetime field 5

custom_json_1 object | null

Custom JSON field 1

custom_json_2 object | null

Custom JSON field 2

custom_json_3 object | null

Custom JSON field 3

custom_json_4 object | null

Custom JSON field 4

custom_json_5 object | null

Custom JSON field 5

list_ids string[] required

Array of list IDs to subscribe the contact to

Response

200 Subscription successful object
success boolean

Whether the subscription was successful

Example true
400 Bad request - validation failed object
error string required

Error message

401 Unauthorized - invalid or missing authentication token object
error string required

Error message

500 Internal server error object
error string required

Error message