AudiencePoint Logo
API docs by Redocly

AudiencePoint APIs (1.5)

Download OpenAPI specification:Download

API Support: engineering@audiencepoint.com URL: https://audiencepoint.com License: Apache 2.0

These APIs are for AudiencePoint client use only. All API integrations must be approved before access.

Introduction

AudiencePoint Scoring API

  • An API designed for customers to integrate into our scoring platform and retrieve scores on demand.

AudiencePoint Event Ingestion API

  • An API designed for customers to stream event data to our platform in real time.

AudiencePoint Email Verification API

AudiencePoint List Subscription API

  • An API designed for customers to subscribe to changes of scores for specific email addresses when AudiencePoint receives new data.

AudiencePoint Send Time Optimization (STO) API

  • An API designed for customers to determine when to send to specific email addresses.

AudiencePoint Inbox Placement API

  • An API designed for customers to see if their emails are being delivered to the inbox or spam folder.

Authentication

AudiencePoint uses an API Key for access to its APIs. Every request to the API must include the X-API-Key in the header.

api_key

API Keys can be requested through your account manager.

Security Scheme Type: API Key
Header parameter name: X-API-Key

Hashing Email Addresses

AudiencePoint Scoring API supports the hashing of email addresses as a secure way of passing personal information. All hashed emails must use the same hashing algorithm or the hashed values will not return any scores.

Steps to convert a plain text email address to a hash

  1. Strip leading and trailing whitespace from the email address
  2. Convert all letters to lowercase
  3. Hash the email address using the SHA-256 algorithm

Example

  1. bigtest39336@ignore.marketing to SHA-256 is 05afa6c180d5afea44d44edcb1189d3b6cc883bd91337a58a82b2b0dd8609ec8
  2. BIGTEST39336@ignore.marketing to SHA-256 is 05afa6c180d5afea44d44edcb1189d3b6cc883bd91337a58a82b2b0dd8609ec8

Score Definitions

Shareable PDF file providing more information on the 'Scores Model'.

ListFit Engagement - Data Dictionary.pdf

Verification Definitions

Shareable PDF file providing more information on the 'Email Verification Model'.

ListFit Verification - Data Dictionary.pdf

Inbox Placement Definitions

Shareable PDF file providing more information on the 'Inbox Placement Model'.

ListFit Inbox Placement - Data Dictionary.pdf

Email Verification SDK

A JavaScript SDK for the Email Verification API.

https://github.com/audiencepoint/ap-js-email-verification-sdk

The Scores Model

emailAddress
required
string

The email address originally provided in the request body.

matched
required
string
Enum: "yes" "no" "invalid" "err"

Indicates if an address has any tracked activity in our dataset.

domain_owner
string

The domain name for the mail provider of the email address.

best_day_of_week
string
Enum: "Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday" "Saturday"

The best day of the week to send to this email address.

best_time_of_day
string
Enum: "Morning" "Afternoon" "Evening" "Night"

The best time of the day to send to this email address.

last_touch
string

The last time (UTC) this email address had an open or a click event.

send_time
string [ 0 .. 167 ]

The ideal day and time to send to an email address.

score
string [ 0 .. 5 ]

How likely a subscriber is to interact with an email.

frequency
string
Enum: "Hyper-engaged" "No Limit" "Daily" "Weekly" "Monthly"

How often an email address typically engages with email across our database.

codes
string

A pipe delimited string containing the industries the subscriber engages with most.

devices
string
Enum: "Desktop" "Tablet" "Mobile" "Unknown" "Unspecified" "Other"

A pipe delimited string containing the type of devices an email has engaged with.

email_clients
string

A pipe delimited string containing the type of email clients an email has engaged.

first_touch
string

The first time (UTC) that a subscriber showed activity.

last_send_no_bounce
string

The last time (UTC) that a subscriber was sent an email and no bounce was returned.

last_seen
string

The date and time (UTC) of the most recent record of an open, click, or unsubscribe from a subscriber.

last_seen_auto_open
string
Enum: "TRUE" "FALSE"

A boolean value that indicates if the last seen event is an auto-open which would be attributed to Apple MPP, Gmail, or Yahoo Proxies.

{
  • "emailAddress": "bigtest39336@ignore.marketing",
  • "matched": "yes",
  • "domain_owner": "google.com",
  • "best_day_of_week": "Monday",
  • "best_time_of_day": "Morning",
  • "last_touch": "2022-12-14 09:04:00 AM",
  • "send_time": "10",
  • "score": "5",
  • "frequency": "Weekly",
  • "codes": "446120|448140|448120",
  • "devices": "Mobile|Desktop",
  • "email_clients": "Gmail|iOS",
  • "first_touch": "2015-10-09 09:04:00 AM",
  • "last_send_no_bounce": "2022-12-14 09:04:00 AM",
  • "last_seen": "2022-12-14 09:04:00 AM",
  • "last_seen_auto_open": "FALSE"
}

The Event Ingestion Model

email
required
string

The plaintext or SHA-256 hashed email address of the event.

type
required
string
Enum: "Open" "Click" "Send" "SoftBounce" "HardBounce" "Unsubscribe" "Complaint"

Indicates the type of email event.

occurred_at_utc
required
string

The date and time (UTC) the email event occurred in the format <YYYY-MM-DDThh:mm:ss>

send_id
required
string

The send event identifier.

domain
string

The domain of the email address (the part after the '@' symbol).

client
string

Email client the event came from.

browser
string

Internet browser the event came from.

os
string

Operating system the event came from.

device
string

Device the event came from.

ip_address
string

IP address the event came from.

user_agent
string

The characteristic string that lets servers and network peers identify the application, operating system, vendor, and/or version of the requesting user agent.

machine_open
boolean
Default: false

This field serves to indicate if an open event was triggered by Apple Mail Privacy Protection (MPP). A value of true means that the open event was caused by a recipient using MPP, while a value of false signifies that the event resulted from a traditional open.

bounce_code
string

The SMTP response code indicating the type of bounce for a failed email delivery. Ensure the bounce_code matches standard SMTP error codes for accurate processing.

bounce_reason
string

A descriptive message that explains the reason for the email bounce. The bounce_reason provides diagnostic information that complements the bounce_code for more precise error handling.

{
  • "email": "bigtest39336@ignore.marketing",
  • "type": "HardBounce",
  • "occurred_at_utc": "2023-04-04T04:50:44",
  • "send_id": "123",
  • "domain": "ignore.marketing",
  • "client": "Hotmail",
  • "browser": "Chrome",
  • "os": "Windows",
  • "device": "PC",
  • "ip_address": "127.0.0.1",
  • "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
  • "machine_open": true,
  • "bounce_code": "550",
  • "bounce_reason": "Server Too Busy"
}

The Email Verification Model

Email
required
string

The email address originally provided in the request.

Result
required
string
Enum: "Verified" "Invalid" "Spamtrap" "Role" "Caution" "Unknown" "Abandoned"

The validation and verification result status of the provided email address.

"Verified" - The email address exists.
"Invalid" - The email address is syntactically invalid, contains a common domain spelling mistake, does not accept incoming mail, or is known to not exist.
"Spamtrap" - The email address is a known spam trap.
"Role" - This is a role based email address (e.g., admin, postmaster, team).
"Caution" - This is a valid email address, but we recommend against emailing it in most cases. The email is either known to be on a global suppression list, known to be a disposable, abuse, or bot email, or known to be a frequent complainer.
"Abandoned" - This once was a verified email address, but it has shown no signs of activity in the past 365 days.
"Unknown" - The email address is in valid format but we are unable to verify that it exists.

Suggestion
string

In certain cases where the email address is invalid, a suggestion will be given on how to fix it.
If the email is syntactically invalid, we will suggest checking the email for correctness (e.g., 'The provided email is not in valid email address format, please check for correctness.').
If the email address contains a misspelling of a common domain, we will suggest a domain correction of the provided email (e.g., if 'testemail@gnail.com' is provided, 'testemail@gmail.com' will be suggested).

{
  • "Email": "testemail@yaho.con",
  • "Result": "Invalid",
  • "Suggestion": "testemail@yahoo.com"
}

The List Subscription Model

new
required
int

The number of new email subscriptions added.

existing
required
int

The number of requested email subscriptions that were already existing subscriptions.

invalid
required
int

The number of requested email subscriptions that could not be subscribed to due to invalid email address/hash format.

{
  • "new": 2,
  • "existing": 1,
  • "invalid": 2
}

The STO Model

required
Array of objects (EmailsWithSendTime) <= 30 items

List of email addresses with their send times

startTimeUtc
required
datetime

start time of campaign in UTC

endTimeUtc
required
datetime

end time of campaign in UTC

defaultSendTIme
datetime

default send time to send to emails in UTC. If not specified in request, set to 20 minutes after endTimeUtc.

{
  • "emailAddresses": [
    ],
  • "startTimeUtc": "2024-01-01T00:00:00",
  • "endTimeUtc": "2024-03-10T22:00:00",
  • "defaultSendTIme": "2024-02-17T11:00:00"
}

The Inbox Placement Model

email
required
string

The email address originally provided in the request.

result
required
string
Enum: "Inbox" "Spam" "Unknown" "NA"

The inbox placement result status of the provided email address.

"Inbox" - Your email is successfully reaching the subscriber's inbox.
"Spam" - Your email is not reaching the subscriber's inbox and is likely being filtered into the spam folder.
"Unknown" - Email is being sent to this subscriber but we cannot confirm inbox placement due to lack of data.
"NA" - AudiencePoint has not received send data for this subscriber, or it is an invalid email address/hash.

provider
required
string

The provider of the email's domain.

{
  • "email": "testemail@yahoo.com",
  • "result": "Spam",
  • "provider": "Yahoo"
}

Scores

Retrieve scores

Endpoint to pass an array of email addresses and have an array of scores returned for each address

Authorizations:
api_key
header Parameters
X-API-Key
string
Example: 349:u1QHNv2rLn2tFdAo6TUIP8r2fnjH0YRg7epsEdN0
Request Body schema: application/json

JSON Object containing an array of plain text or SH-256 email addresses and an optional array of scores to return

emailAddresses
Array of strings <email address OR SHA-256> <= 200 items

Array of plain text or SHA-256 email addresses

scoreSelection
Array of strings <score names>

Optional array of specific scores to be returned. If this parameter is not proivded or is empty, all scores will be returned. Score options -
["domain_owner", "best_day_of_week", "best_time_of_day", "last_touch", "send_time", "score", "frequency", "codes", "devices", "email_clients", "first_touch", "last_send_no_bounce", "last_seen", "last_seen_auto_open"]
See 'The Scores Model' section on the left for more information about the scores.

Responses

Request samples

Content type
application/json
{
  • "emailAddresses": [
    ],
  • "scoreSelection": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Event Ingestion

Send event data

Endpoint to send event data in real time.

Authorizations:
api_key
header Parameters
X-API-Key
string
Example: 349:u1QHNv2rLn2tFdAo6TUIP8r2fnjH0YRg7epsEdN0
Request Body schema: application/json

JSON Object containing an array of email event objects

Array of objects (EmailEvent) <= 30 items

Array of email event objects

Responses

Request samples

Content type
application/json
{
  • "events": [
    ]
}

Response samples

Content type
application/json
{
  • "SequenceNumber": "49641413016779683157064666432340754120125478138187505682",
  • "ShardId": "shardId-000000000001"
}

Email Verification

Verify with GET request

(Method Not Recommended)

GET request method to pass an email address as a query and have a verification result returned.
We recommend using the POST request method because query parameters in a GET request are included as part of the URL (and appear in browsers' address bars). This means they are liable to be recorded, cached, and exposed in ways most other web traffic data is not.

Authorizations:
api_key
query Parameters
email
required
string
Example: email=bigtest123@ignore.marketing
header Parameters
X-API-Key
string
Example: 349:u1QHNv2rLn2tFdAo6TUIP8r2fnjH0YRg7epsEdN0

Responses

Request samples 

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.audiencepoint.com/v1/email-verification?email=testemail@gmail.com");
request.Headers.Add("x-api-key", "YOUR_API_KEY");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Result.Content.ReadAsStringAsync());

Response samples

Content type
application/json
{
  • "Email": "testemail@yaho.con",
  • "Result": "Invalid",
  • "Suggestion": "testemail@yahoo.com"
}

Verify with POST request

POST request method to verify an email address

Authorizations:
api_key
header Parameters
X-API-Key
string
Example: 349:u1QHNv2rLn2tFdAo6TUIP8r2fnjH0YRg7epsEdN0
Request Body schema: application/json

JSON Object containing a plain text email address

email
string

A plain text email address

Responses

Request samples

Content type
application/json
{
  • "email": "testemail@yaho.con"
}

Response samples

Content type
application/json
{
  • "Email": "testemail@yaho.con",
  • "Result": "Invalid",
  • "Suggestion": "testemail@yahoo.com"
}

List Subscription

Subscribe to email addresses

Endpoint to pass an array of email addresses one wishes to subscribe to

Authorizations:
api_key
header Parameters
X-API-Key
string
Example: 349:u1QHNv2rLn2tFdAo6TUIP8r2fnjH0YRg7epsEdN0
Request Body schema: application/json

JSON Object containing an array of plain text or SH-256 email addresses

emailAddresses
Array of strings <email address OR SHA-256>

Array of plain text or SHA-256 email addresses

Responses

Request samples

Content type
application/json
{
  • "emailAddresses": [
    ]
}

Response samples

Content type
application/json
{
  • "new": 2,
  • "existing": 1,
  • "invalid": 2
}

STO

Retrieve send times between two dates

Endpoint to pass an array of email addresses, start time in Coordinated Universal Time, end time in Coordinated Universal Time, and an optional default send time. This returns all the email addresses along with their send times, the start time utc, end time utc, and default send time. If default send time is not passed initially, the default send time that is returned is set to 20 minutes after the end time.

Authorizations:
api_key
header Parameters
X-API-Key
string
Example: 349:dLHbIMy3wBb44IQs3sHd1bNorqwwDAF8B85sdJBd
Request Body schema: application/json

JSON Object containing an array of plain text or SH-256 email addresses, start time utc, end time utc, and optional default send time

emailAddresses
Array of strings <email address OR SHA-256> <= 30 items

Array of plain text or SHA-256 email addresses

startTimeUtc
datetime

start time of campaign

endTimeUtc
datetime

end time of campaign

defaultSendTime
datetime

default send time if set

Responses

Request samples

Content type
application/json
{
  • "emailAddresses": [
    ],
  • "startTimeUtc": "2024-01-01T00:00:00",
  • "endTimeUtc": "2024-03-10T20:00:00",
  • "defaultSendTime": "2024-02-17T11:00:00"
}

Response samples

Content type
application/json
[
  • {
    }
]

Inbox Placement

Retrieve inbox placement scores

Endpoint to pass an array of email addresses and have an inbox placement score returned for each address

Authorizations:
api_key
header Parameters
X-API-Key
string
Example: 349:u1QHNv2rLn2tFdAo6TUIP8r2fnjH0YRg7epsEdN0
Request Body schema: application/json

JSON Object containing an array of plain text or SH-256 email addresses

emailAddresses
Array of strings <email address OR SHA-256> <= 200 items

Array of plain text or SHA-256 email addresses

Responses

Request samples

Content type
application/json
{
  • "emailAddresses": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]