Lists

Subscribe to email lists

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

Subscribe a contact to one or more email lists. This is a public endpoint that doesn't require authentication.

Important: This endpoint subscribes contacts to public lists only. To add a contact to a private list, use the authenticated /api/lists.subscribe endpoint with a bearer token. A valid email_hmac in the contact object only lets the contact confirm a pending double opt-in on a private list: it never adds them to one, nor back to one they left.

If the list has double opt-in enabled, a confirmation email will be sent.

Body application/json

workspace_id string required

The ID of the workspace

  • Example: ws_1234567890
contact object required
Show 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.

  • Available options: granted, denied
tracking_clicks_consent string

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

  • Available 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

500 Internal server error object
error string required

Error message