Email Opt-in API Documentation
Overview
The Email Opt-in API allows you to capture email opt-ins and receive comprehensive consumer information. This API is designed to process email subscriptions while providing detailed demographic, financial, and behavioral insights about your subscribers, enabling more targeted marketing and personalized customer interactions.
How It Works
The Email Opt-in API works through the following process:
- Submit Email Opt-in: You send the subscriber's email along with any additional information you have, such as name or phone number.
- Matching Process: The system processes the opt-in and attempts to match the provided information against a comprehensive consumer database.
- Data Enrichment: When a match is found, the API returns detailed consumer data, including demographic information, financial details, property data, and behavioral insights.
- Response Handling: You can use the enriched data to better understand your subscribers, personalize marketing efforts, or enhance your CRM records with valuable consumer insights.
Authentication
Most mutations and queries require authentication.
The auth
object must be provided as
part of the request. It includes:
Auth Object
Field | Type | Description |
---|---|---|
appId |
String | The application ID. Request this from [email protected]. |
appSecret |
String | The application secret. Request this from [email protected]. |
Operations
Mutation: email
Captures email opt-ins and returns enriched consumer data.
Endpoint
mutation Email(
$auth: AuthRequestInput!,
$event: EmailOptinEventInput!
) {
email(auth: $auth, event: $event) {
code
data
message
}
}
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
auth |
AuthRequestInput | Yes | The authentication credentials. |
event |
EmailOptinEventInput | Yes | Details of the email opt-in. |
EmailOptinEventInput
Fields
Field | Type | Required | Description |
---|---|---|---|
email |
String | Yes | Email address of the subscriber. |
pixel_id |
Int | Yes | The unique ID for the pixel. |
domain |
String | Yes | The domain where the event occurred. |
pusher_channel |
String | No | Pusher channel identifier. |
first_name |
String | No | First name of the subscriber. |
last_name |
String | No | Last name of the subscriber. |
tcpa |
Int | No | TCPA compliance flag. |
phone |
String | No | Phone number of the subscriber. |
md5 |
String | No | MD5 hash for identification. |
hem |
String | No | HEM identifier. |
request_id |
String | No | Unique request identifier. |
as |
String | No | AS identifier. |
canonical |
String | No | Canonical URL. |
city |
String | No | City of the subscriber. |
country |
String | No | Country of the subscriber. |
description |
String | No | Description of the event. |
ip |
String | No | IP address of the subscriber. |
isp |
String | No | Internet Service Provider. |
language |
String | No | Language preference of the user. |
lat |
Float | No | Latitude coordinate. |
lon |
Float | No | Longitude coordinate. |
org |
String | No | Organization. |
referrer |
String | No | Referring URL. |
timestamp |
Int | No | Timestamp of the event. |
timezone |
String | No | Timezone of the subscriber. |
title |
String | No | Page title. |
url |
String | No | Current URL. |
sessionid |
String | No | Session identifier. |
zip |
String | No | ZIP/Postal code. |
age |
String | No | Age of the subscriber. |
gender |
String | No | Gender of the subscriber. |
sha1 |
String | No | SHA-1 hash. |
sha2 |
String | No | SHA-2 hash. |
nonId |
String | No | Non-ID identifier. |
utm_source |
String | No | UTM source parameter. |
utm_medium |
String | No | UTM medium parameter. |
utm_campaign |
String | No | UTM campaign parameter. |
utm_term |
String | No | UTM term parameter. |
utm_content |
String | No | UTM content parameter. |
os |
String | No | Operating system. |
fingerprint |
String | No | Browser fingerprint. |
user_agent |
String | No | User agent string. |
browser |
String | No | Browser name and version. |
device_type |
String | No | Type of device. |
resolution |
String | No | Screen resolution. |
event |
String | No | Event type. |
region_name |
String | No | Region/state name. |
country_code |
String | No | Country code. |
unique_id |
String | No | Unique identifier. |
is_new_session |
Boolean | No | Whether this is a new session. |
is_eu |
Boolean | No | Whether the user is in the EU. |
referring_domain |
String | No | Referring domain. |
inner_resolution |
String | No | Inner window resolution. |
custom_one |
String | No | Custom field one. |
custom_two |
String | No | Custom field two. |
custom_three |
String | No | Custom field three. |
custom_four |
String | No | Custom field four. |
custom_five |
String | No | Custom field five. |
Example Request
{
"query": "mutation Email($auth: AuthRequestInput!, $event: EmailOptinEventInput!) { email(auth: $auth, event: $event) { code data message } }",
"variables": {
"auth": {
"appId": "yourAppIdHere",
"appSecret": "yourAppSecretHere"
},
"event": {
"email": "[email protected]",
"pixel_id": 123,
"domain": "example.com",
"first_name": "John",
"last_name": "Smith"
}
}
}
Example CURL Request
curl -X POST https://sweet-colt-9750.ddn.hasura.app/graphql \
-H "Content-Type: application/json" \
-d '{
"query": "mutation Email($auth: AuthRequestInput!, $event: EmailOptinEventInput!) { email(auth: $auth, event: $event) { code data message } }",
"variables": {
"auth": {
"appId": "yourAppIdHere",
"appSecret": "yourAppSecretHere"
},
"event": {
"email": "[email protected]",
"pixel_id": 123,
"domain": "example.com",
"first_name": "John",
"last_name": "Smith"
}
}
}'
Example Response
{
"data": {
"email": {
"code": 200,
"data": {
"consumer_data": {
"pusher_channel": null,
"event": "email_optin",
"team_id": 1,
"first_name": "John",
"last_name": "Smith",
"website_id": 123,
"pixel_id": 123,
"domain": "example.com",
"canonical": "undefined",
"consumer_id": "10000001",
"isUniqueLead": false,
"created_at": 1716979200,
"timestamp": "2024-05-29 12:00:00.000",
"tcpa": null,
"hem": "",
"sha2": "",
"email": "[email protected]",
"country_code": "",
"is_eu": false,
"lat": 0,
"lon": 0,
"timezone": "",
"language": "",
"request_id": null,
"description": null,
"ip": "",
"url": "undefined",
"nonId": null,
"is_new_session": null,
"as": null,
"title": null,
"sessionid": null,
"fingerprint": null,
"unique_id": "a1b2c3d4e5f6g7h8i9j0",
"org": "",
"isp": "",
"referrer": "",
"referring_domain": "",
"utm_source": "",
"utm_medium": "",
"utm_campaign": "",
"utm_term": "",
"utm_content": "",
"os": "",
"user_agent": "",
"_unmapped_data": "",
"browser": "",
"device_type": "",
"resolution": "",
"inner_resolution": "",
"custom_one": "",
"custom_two": "",
"custom_three": "",
"custom_four": "",
"custom_five": "",
"phone": "",
"phone_formatted": "",
"phone_voip": "",
"phone_carrier": "",
"phone_type": "",
"phone_dialing_code": 0,
"phone_do_not_call": false,
"phone_activity": "",
"phone_is_callable": false,
"phone_can_receive_texts": false,
"md5": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"sha1": "",
"address": "123 Main St",
"city": "Washington",
"region_name": "DC",
"zip": "20001",
"country": "United States",
"age": 45,
"gender": "Male",
"multilingual": false,
"marital_status": "Married",
"ethnic_group": "",
"generation": "Generation X",
"political_party": "Independent",
"religion": "Christian",
"education": "College Graduate",
"occupation_detail": "Professional",
"income_hh": "$100,000 - $150,000",
"net_worth_hh": "$500,000 - $999,999",
"income_levels": "",
"credit_range": "750-799",
"new_credit_offered_hh": false,
"amex_card": false,
"bank_card": false,
"owns_investments": false,
"premium_amex_card": false,
"premium_card": false,
"owns_stocks_and_bonds": false,
"political_contributor": false,
"premium_income_hh": "",
"income_midpts_hh": 0,
"home_owner": "Home Owner",
"dwelling_type": "Single Family",
"home_heat_type": "",
"home_price": 350000,
"home_purchased_years_ago": 5,
"home_value": 400000,
"mortgage_age": 5,
"mortgage_amount": 280000,
"mortgage_loan_type": "Conventional",
"mortgage_refi_age": 2,
"mortgage_refi_amount": "250000",
"mortgage_refi_type": "Fixed",
"urbanicity": "Urban",
"child_aged_0_3_hh": 0,
"child_aged_4_6_hh": 1,
"child_aged_7_9_hh": 1,
"child_aged_10_12_hh": 0,
"child_aged_13_18_hh": 0,
"veteran_hh": 0,
"num_persons_hh": 4,
"num_adults_hh": 2,
"num_children_hh": 2,
"number_of_vehicles_in_hh": 2,
"ledger": {
"credits_pixel_total": 500,
"credits_team_balance": 10000,
"credits_team_today": 1,
"credits_pixel_today": 1
}
}
},
"message": "Success"
}
}
}
Response Object
The response object for all API calls adheres to the following structure:
export interface ApiResponseType {
code: number;
message: string;
data: sdk.JSONValue;
}
-
code
: Indicates the result of the operation.200
: Successful operation.-
400
: Client error, such as invalid input. 500
: Server error.
-
message
: A descriptive message about the operation's outcome. -
data
: Contains the result of the operation. For errors, this will be an empty object.
For all error responses, the data
field
will be an empty object, and the
message
field will describe the issue
encountered.
Contact
For additional support or questions about the Email API, contact our development team at [email protected].