The Engagement API from Return Path — 35 operation(s) for engagement.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/return-path-engagement-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Everest Engagement API
version: '2.0'
summary: Email deliverability, inbox placement, sender reputation and DMARC intelligence — the Validity Everest API, the surviving surface of the Return Path platform.
description: 'API Limit: 500 requests per minute. Limit increases are available on a per-customer basis by contacting our support team.
Welcome to the Everest API (V2) by Validity. We''ll be rolling out additional product support in the coming months. It''s important to note that V2 of our API is purely optional. We hope you find it simpler to use, more intuitive, and better documented, but we plan to continue supporting API V1.
All API requests utilize REST methods resulting in JSON, XML, CSV, or Serialized output. To request new API functionality please feel free to contact us.
Every API request requires the use of the X-API-KEY header, which is located in your account settings.
Throughout the documentation you''ll see the use of variables like YOUR_API_KEY that can be swapped out using your real API key. If you use Postman, this collection is available for download along with a shared variable template to define your host and apikey variables.
All datetime fields are UTC.
Standard API Responses
200 Success
401 Unauthorized (no valid API key provided)
403 Forbidden (indicates lack access to the action you''re performning)
404 Not Found (indicates invalid parameters or missing API endpoint)
429 Too Many Requests (API limits have been reached, retry after some time)
500 Internal Server Error (indicates something went wrong on our end)
Each 400-level error code will contain an status object containing a description of the problem.'
contact:
name: Validity Support
url: https://knowledge.validity.com/
x-derived-from: collections/return-path-everest-api.postman_collection.json
x-source-url: https://developer.everest.validity.com/
x-provenance: DERIVED by API Evangelist from the Postman collection Validity publishes at developer.everest.validity.com. Validity does not publish an OpenAPI document; every path, method, parameter, header, request body and response example here is read verbatim from that collection.
servers:
- url: https://api.everest.validity.com/api
description: 'Everest API. The major version is the first path segment: 2.0 is current, 1.0 is the legacy API Validity says it will continue to support.'
security:
- apiKeyAuth: []
tags:
- name: Engagement
paths:
/2.0/analytics/events/read:
get:
operationId: engagementOverviewDetailedReadEvents
summary: Detailed Read Events
tags:
- Engagement
description: Please see timezone param list for details about the id's.
x-api-version: '2.0'
responses:
'200':
description: Success
'401':
description: Unauthorized — no valid API key provided
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden — the key lacks access to this action
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found — invalid parameters or missing API endpoint
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too Many Requests — API rate limit reached, retry later
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/2.0/analytics/events/click:
get:
operationId: engagementOverviewDetailedClickEvents
summary: Detailed Click Events
tags:
- Engagement
description: Please see timezone param list for details about the id's.
x-api-version: '2.0'
responses:
'200':
description: Success
'401':
description: Unauthorized — no valid API key provided
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden — the key lacks access to this action
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found — invalid parameters or missing API endpoint
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too Many Requests — API rate limit reached, retry later
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/2.0/analytics/events/forward:
get:
operationId: engagementOverviewDetailedForwardEvents
summary: Detailed Forward Events
tags:
- Engagement
description: Please see timezone param list for details about the id's.
x-api-version: '2.0'
responses:
'200':
description: Success
'401':
description: Unauthorized — no valid API key provided
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden — the key lacks access to this action
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found — invalid parameters or missing API endpoint
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too Many Requests — API rate limit reached, retry later
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/2.0/analytics/events/print:
get:
operationId: engagementOverviewDetailedPrintEvents
summary: Detailed Print Events
tags:
- Engagement
description: Please see timezone param list for details about the id's.
x-api-version: '2.0'
responses:
'200':
description: Success
'401':
description: Unauthorized — no valid API key provided
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden — the key lacks access to this action
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found — invalid parameters or missing API endpoint
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too Many Requests — API rate limit reached, retry later
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/2.0/analytics/distribution/desktop:
get:
operationId: engagementOverviewPlatformRecipients
summary: Platform Recipients
tags:
- Engagement
description: Please see timezone param list for details about the id's.
x-api-version: '2.0'
responses:
'200':
description: OK
content:
text/plain:
example: "{\n \"meta\": {\n \"params\": {\n \"startdate\": \"2021-09-06T00:00:00+00:00\",\n \"enddate\": \"2021-10-05T00:00:00+00:00\",\n \"source\": null,\n \"integrationkey\": null,\n \"provider\": null,\n \"todomain\": null,\n \"pixel\": null,\n \"campaign_id\": null,\n \"platform\": null,\n \"country\": null,\n \"region\": null,\n \"city\": null,\n \"enthusiasm\": null,\n \"timeofday\": null,\n \"timezone\": null,\n \"recipient\": null\n },\n \"total\": 3,\n \"limit\": 5000,\n \"pages\": 1\n },\n \"results\": [\n {\n \"toaddress\": \"recipient1@domain.com\",\n \"firstseen\": \"9/6/2021\",\n \"lastseen\": \"10/4/2021\",\n \"country\": null,\n \"region\": null,\n \"city\": null,\n \"platform\": \"Desktop\",\n \"device\": \"Windows\",\n \"client\": \"Edge\",\n \"timezone\": null\n },\n {\n \"toaddress\": \"recipient2@domain.com\",\n \"firstseen\": \"9/17/2021\",\n \"lastseen\": \"9/17/2021\",\n \"country\": null,\n \"region\": null,\n \"city\": null,\n \"platform\": \"Desktop\",\n \"device\": \"Windows\",\n \"client\": \"Edge\",\n \"timezone\": null\n },\n {\n \"toaddress\": \"recipient3@domain.com\",\n \"firstseen\": \"9/14/2021\",\n \"lastseen\": \"9/21/2021\",\n \"country\": null,\n \"region\": null,\n \"city\": null,\n \"platform\": \"Desktop\",\n \"device\": \"Windows\",\n \"client\": \"Edge\",\n \"timezone\": null\n }, ...\n ]\n}"
'401':
description: Unauthorized — no valid API key provided
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden — the key lacks access to this action
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found — invalid parameters or missing API endpoint
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too Many Requests — API rate limit reached, retry later
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/2.0/analytics/engagement/activity:
get:
operationId: engagementOverviewRecentActivity
summary: Recent Activity
tags:
- Engagement
description: Please see timezone param list for details about the id's.
x-api-version: '2.0'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
meta:
type: object
properties:
params:
type: object
properties:
startdate:
type: string
enddate:
type: string
timeofday:
type: array
items:
type: string
platform:
type: array
items:
type: string
country:
type: array
items:
type: string
provider: {}
todomain: {}
pixel: {}
campaign_id: {}
region: {}
timezone_id: {}
enthusiasm: {}
device_id: {}
client_id: {}
recipient: {}
opens:
type: integer
uniques:
type: integer
forwards:
type: integer
uniqueforwards:
type: integer
prints:
type: integer
uniqueprints:
type: integer
results:
type: array
items:
type: object
properties:
day:
type: string
opens:
type: integer
uniques:
type: integer
forwards:
type: integer
uniqueforwards:
type: integer
prints:
type: integer
uniqueprints:
type: integer
examples:
Recent Activity:
value:
meta:
params:
startdate: '2020-12-15T05:00:00+00:00'
enddate: '2021-01-14T05:00:00+00:00'
timeofday:
- morning
platform:
- desktop
- mobile
country:
- US
provider: null
todomain: null
pixel: null
campaign_id: null
region: null
timezone_id: null
enthusiasm: null
device_id: null
client_id: null
recipient: null
opens: 4896
uniques: 2072
forwards: 17
uniqueforwards: 14
prints: 595
uniqueprints: 365
results:
- day: '2020-12-15'
opens: 198
uniques: 104
forwards: 3
uniqueforwards: 2
prints: 14
uniqueprints: 12
- day: '2020-12-16'
opens: 228
uniques: 111
forwards: 3
uniqueforwards: 3
prints: 19
uniqueprints: 15
- day: '2020-12-17'
opens: 58
uniques: 29
forwards: 6
uniqueforwards: 4
prints: 12
uniqueprints: 5
- day: '2020-12-18'
opens: 76
uniques: 36
forwards: 3
uniqueforwards: 3
prints: 5
uniqueprints: 5
- day: '2020-12-19'
opens: 29
uniques: 16
forwards: 0
uniqueforwards: 0
prints: 3
uniqueprints: 3
- day: '2020-12-20'
opens: 28
uniques: 18
forwards: 0
uniqueforwards: 0
prints: 5
uniqueprints: 3
- day: '2020-12-21'
opens: 278
uniques: 111
forwards: 0
uniqueforwards: 0
prints: 27
uniqueprints: 10
- day: '2020-12-22'
opens: 114
uniques: 56
forwards: 0
uniqueforwards: 0
prints: 6
uniqueprints: 6
- day: '2020-12-23'
opens: 121
uniques: 63
forwards: 0
uniqueforwards: 0
prints: 23
uniqueprints: 10
- day: '2020-12-24'
opens: 63
uniques: 40
forwards: 0
uniqueforwards: 0
prints: 28
uniqueprints: 19
- day: '2020-12-25'
opens: 24
uniques: 20
forwards: 0
uniqueforwards: 0
prints: 14
uniqueprints: 13
- day: '2020-12-26'
opens: 180
uniques: 53
forwards: 0
uniqueforwards: 0
prints: 14
uniqueprints: 13
- day: '2020-12-27'
opens: 37
uniques: 15
forwards: 0
uniqueforwards: 0
prints: 9
uniqueprints: 6
- day: '2020-12-28'
opens: 206
uniques: 76
forwards: 0
uniqueforwards: 0
prints: 24
uniqueprints: 14
- day: '2020-12-29'
opens: 179
uniques: 69
forwards: 0
uniqueforwards: 0
prints: 11
uniqueprints: 10
- day: '2020-12-30'
opens: 144
uniques: 65
forwards: 0
uniqueforwards: 0
prints: 11
uniqueprints: 10
- day: '2020-12-31'
opens: 112
uniques: 60
forwards: 0
uniqueforwards: 0
prints: 20
uniqueprints: 12
- day: '2021-01-01'
opens: 102
uniques: 39
forwards: 0
uniqueforwards: 0
prints: 33
uniqueprints: 14
- day: '2021-01-02'
opens: 60
uniques: 33
forwards: 0
uniqueforwards: 0
prints: 11
uniqueprints: 11
- day: '2021-01-03'
opens: 204
uniques: 67
forwards: 0
uniqueforwards: 0
prints: 16
uniqueprints: 10
- day: '2021-01-04'
opens: 433
uniques: 119
forwards: 0
uniqueforwards: 0
prints: 29
uniqueprints: 15
- day: '2021-01-05'
opens: 273
uniques: 140
forwards: 0
uniqueforwards: 0
prints: 30
uniqueprints: 21
- day: '2021-01-06'
opens: 367
uniques: 130
forwards: 0
uniqueforwards: 0
prints: 21
uniqueprints: 15
- day: '2021-01-07'
opens: 251
uniques: 128
forwards: 0
uniqueforwards: 0
prints: 46
uniqueprints: 22
- day: '2021-01-08'
opens: 127
uniques: 70
forwards: 1
uniqueforwards: 1
prints: 38
uniqueprints: 20
- day: '2021-01-09'
opens: 185
uniques: 66
forwards: 1
uniqueforwards: 1
prints: 16
uniqueprints: 12
- day: '2021-01-10'
opens: 81
uniques: 47
forwards: 0
uniqueforwards: 0
prints: 17
uniqueprints: 14
- day: '2021-01-11'
opens: 305
uniques: 99
forwards: 0
uniqueforwards: 0
prints: 26
uniqueprints: 14
- day: '2021-01-12'
opens: 304
uniques: 123
forwards: 0
uniqueforwards: 0
prints: 31
uniqueprints: 14
- day: '2021-01-13'
opens: 129
uniques: 69
forwards: 0
uniqueforwards: 0
prints: 36
uniqueprints: 17
'401':
description: Unauthorized — no valid API key provided
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden — the key lacks access to this action
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found — invalid parameters or missing API endpoint
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too Many Requests — API rate limit reached, retry later
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/2.0/analytics/distribution:
get:
operationId: engagementOverviewPlatformDistribution
summary: Platform Distribution
tags:
- Engagement
description: 'The Apple Privacy Proxy pre-fetches images (upon delivery) for devices on a charger/internet connection, which will inflate your open counts but also serves as a strong indicator of valid addresses. Yahoo! Privacy Proxy is similar since they also pre-fetch images, but only in instances where the recipient is using the Yahoo! mail client. Gmail on the other hand does not pre-fetch images, so the open counts accurately reflect your audience''s open activity. Desktop, mobile, etc. will likely contain Yahoo! or Apple addresses where less restrictive mail clients were in use.
Please see timezone param list for details about the id''s.'
x-api-version: '2.0'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
meta:
type: object
properties:
params:
type: object
properties:
startdate:
type: string
enddate:
type: string
source: {}
integrationkey: {}
provider: {}
todomain: {}
pixel: {}
campaign_id: {}
platform: {}
country: {}
region: {}
city: {}
enthusiasm: {}
timeofday: {}
timezone: {}
recipient: {}
use_case:
type: object
properties:
proxy_apple:
type: string
proxy_google:
type: string
proxy_yahoo:
type: string
desktop:
type: string
mobile:
type: string
tablet:
type: string
other:
type: string
results:
type: object
properties:
proxy_apple:
type: object
properties:
label:
type: string
percent:
type: integer
recipients:
type: integer
opens:
type: integer
endpoints:
type: array
items:
type: string
proxy_google:
type: object
properties:
label:
type: string
percent:
type: number
recipients:
type: integer
opens:
type: integer
endpoints:
type: array
items:
type: string
proxy_yahoo:
type: object
properties:
label:
type: string
percent:
type: integer
recipients:
type: integer
opens:
type: integer
endpoints:
type: array
items:
type: string
desktop:
type: object
properties:
label:
type: string
percent:
type: number
recipients:
type: integer
opens:
type: integer
endpoints:
type: array
items:
type: string
mobile:
type: object
properties:
label:
type: string
percent:
type: number
recipients:
type: integer
opens:
type: integer
endpoints:
type: array
items:
type: string
tablet:
type: object
properties:
label:
type: string
percent:
type: integer
recipients:
type: integer
opens:
type: integer
endpoints:
type: array
items:
type: string
other:
type: object
properties:
label:
type: string
percent:
type: integer
recipients:
type: integer
opens:
type: integer
endpoints:
type: array
items:
type: string
examples:
Platform Distribution:
value:
meta:
params:
startdate: '2021-09-06T00:00:00+00:00'
enddate: '2021-10-05T00:00:00+00:00'
source: null
integrationkey: null
provider: null
todomain: null
pixel: null
campaign_id: null
platform: null
country: null
region: null
city: null
enthusiasm: null
timeofday: null
timezone: null
recipient: null
use_case:
proxy_apple: Valid recipients
proxy_google: Valid recipients, unique opens
proxy_yahoo: Valid recipients
desktop: Valid recipients, opens, geolocation, client/device
mobile: Valid recipients, opens, geolocation, client/device
tablet: Valid recipients, opens, geolocation, client/device
other: otentially false positives (content scanners, bots)
results:
proxy_apple:
label: Apple Privacy Proxy
percent: 0
recipients: 35
opens: 269
endpoints:
- /analytics/distribution/proxy_apple
proxy_google:
label: Google Image Proxy
percent: 17.6
recipients: 458
opens: 180572
endpoints:
- /analytics/distribution/proxy_google
proxy_yahoo:
label: Yahoo! Privacy Proxy
percent: 0
recipients: 3
opens: 3
endpoints:
- /analytics/distribu
# --- truncated at 32 KB (167 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/return-path/refs/heads/main/openapi/return-path-engagement-api-openapi.yml