Contacts

Get a contact by email address

GET https://demo.notifuse.com/api/contacts.getByEmail

Retrieves a contact by their email address within a specific workspace. The response always includes the contact's list subscriptions with their status (active, pending, unsubscribed, bounced, complained).

Authorizations

Authorization string header required

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

Query Parameters

workspace_id string required

The ID of the workspace

  • Example: ws_1234567890
email string<email> required

The email address of the contact

  • Example: user@example.com

Response

200 Contact found successfully object
contact object
Show child attributes
email string<email> required

Email address of the contact. This is the contact's unique identifier.

  • Example: user@example.com
external_id string | null

Identifier for the contact in your own system. Not unique — several contacts may share the same external_id.

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

The contact's own choice about open tracking; null means unknown.

  • Available options: granted, denied, null
tracking_clicks_consent string | null

The contact's own choice about click tracking; null means unknown.

  • Available options: granted, denied, null
tracking_consent_updated_at string<date-time> | null

When a tracking choice last changed.

tracking_consent_source string | null

Where the last tracking choice came from (api, console, import, notification_center, email_link, subscribe_form).

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 any

Custom JSON field 1. Any JSON value, or null.

custom_json_2 any

Custom JSON field 2. Any JSON value, or null.

custom_json_3 any

Custom JSON field 3. Any JSON value, or null.

custom_json_4 any

Custom JSON field 4. Any JSON value, or null.

custom_json_5 any

Custom JSON field 5. Any JSON value, or null.

created_at string<date-time> read-only

When the contact was created (read-only, set by server)

  • Example: 2023-01-15T10:30:00Z
updated_at string<date-time> read-only

When the contact was last updated (read-only, set by server)

  • Example: 2023-04-22T15:45:00Z
contact_lists object[] read-only

Lists the contact is subscribed to (read-only, included in GET responses only)

Show child attributes
email string<email>

Email address of the contact

  • Example: user@example.com
list_id string

ID of the list

  • Example: newsletter
list_name string

Name of the list

  • Example: Newsletter
status string

Subscription status

  • Available options: active, pending, unsubscribed, bounced, complained
  • Example: active
created_at string<date-time>

When the contact was subscribed to this list

  • Example: 2023-01-15T10:30:00Z
updated_at string<date-time>

When the subscription was last updated

  • Example: 2023-01-15T10:30:00Z
deleted_at string<date-time> | null

When the subscription was deleted (null if active)

contact_segments object[] read-only

Segments the contact belongs to (read-only, included in GET responses only)

Show child attributes
email string<email>

Email address of the contact

  • Example: user@example.com
segment_id string

ID of the segment

  • Example: premium_users
version integer<int64>

Version of the segment computation

  • Example: 1
matched_at string<date-time>

When the contact was matched to this segment

  • Example: 2023-01-15T10:30:00Z
computed_at string<date-time>

When the segment was last computed

  • Example: 2023-01-15T10:30:00Z
400 Bad request - missing parameters object
error string required

Error message

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

Error message

404 Contact not found object
error string required

Error message

500 Internal server error object
error string required

Error message