The Inbox Placement API from Return Path — 17 operation(s) for inbox placement.
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-inbox-placement-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 Inbox Placement 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: Inbox Placement
paths:
/2.0/inbox/seeds:
get:
operationId: seedListsSeedList
summary: Seed List
tags:
- Inbox Placement
description: Seed List returns a full list of seed addresses for an account.
x-api-version: '2.0'
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties: {}
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
meta:
type: object
properties:
pages:
type: integer
total:
type: integer
results:
type: array
items:
type: string
examples:
Seed List:
value:
meta:
pages: 1
total: 3
results:
- seed1@domain.com
- seed2@domain.com
- seed3@domain.com
'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'
put:
operationId: seedListsUpdateSeedList
summary: Update Seed List
tags:
- Inbox Placement
x-api-version: '2.0'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
regions:
type: string
description: (Required) Either an array or comma separated list of region ids.
example:
regions: 1,2,3,6,7,8,9,13,15
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
results:
type: object
properties:
status:
type: string
examples:
Update Seed List:
value:
results:
status: 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/inbox/seeds/providers:
get:
operationId: seedListsRegionsProviders
summary: Regions & Providers
tags:
- Inbox Placement
description: Regions & Providers returns a region along with the supported ISPs within it, or a list of targetable regions to configure your seed list.
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/inbox/optimizer:
get:
operationId: listOptimizerAllLists
summary: All Lists
tags:
- Inbox Placement
description: All Lists provides an overview of each available mailing list.
x-api-version: '2.0'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
meta:
type: object
properties:
total:
type: integer
results:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
status:
type: string
size:
type: integer
domains:
type: integer
created:
type: string
examples:
All Lists:
value:
meta:
total: 2
results:
- id: 1
name: Customer List 1
status: complete
size: 497783
domains: 32685
created: '2020-06-26 16:22:36'
- id: 2
name: Customer List 2
status: complete
size: 547764
domains: 30119
created: '2016-06-09 17:20:23'
'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'
post:
operationId: listOptimizerCreateList
summary: Create List
tags:
- Inbox Placement
description: Create List allows submitting a new mailing list sample for analysis.
x-api-version: '2.0'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
type: string
description: Name of the list
list:
type: string
description: List of email addresses or (preferably) the domain portion of the addresses
delimiter:
type: string
description: Separator between email addresses (defaults to new line)
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/inbox/optimizer/{optimizerId}:
get:
operationId: listOptimizerListByID
summary: List by ID
tags:
- Inbox Placement
description: List by ID provides detailed information about a specified mailing list including a full breakdown of each mailbox provider.
x-api-version: '2.0'
parameters:
- name: optimizerId
in: path
required: true
schema:
type: integer
example: '1'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
meta:
type: object
results:
type: object
properties:
id:
type: integer
name:
type: string
status:
type: string
size:
type: integer
known:
type: integer
unknown:
type: integer
weighting_applied:
type: boolean
created:
type: string
regions:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
providers:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
domains:
type: integer
percent:
type: integer
has_seeds:
type: boolean
matches:
type: string
examples:
List by ID:
value:
meta: {}
results:
id: 1
name: Customer List 1
status: complete
size: 500112
known: 468228
unknown: 29555
weighting_applied: true
created: '2020-06-26 16:22:36'
regions:
- id: 3
name: Global
providers:
- id: 111
name: Gmail
domains: 201291
percent: 43
has_seeds: true
matches: /api/2.0/inbox/optimizer/1/domains/111
- id: 222
name: AOL
domains: 50132
percent: 10.7
has_seeds: true
matches: /api/2.0/inbox/optimizer/1/domains/222
- id: 333
name: Hotmail
domains: 40353
percent: 8.6
has_seeds: true
matches: /api/2.0/inbox/optimizer/1/domains/333
- id: 1
name: North America
providers: []
'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'
delete:
operationId: listOptimizerDeleteList
summary: Delete List
tags:
- Inbox Placement
description: Delete List allows you to delete one of your mailing list samples.
x-api-version: '2.0'
parameters:
- name: optimizerId
in: path
required: true
schema:
type: integer
example: '1'
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'
put:
operationId: listOptimizerApplyListWeighting
summary: Apply List Weighting
tags:
- Inbox Placement
description: Apply List Weighting enables you to weight your seedlist based on the results of a Seedlist Optimizer sample. See Create List for instructions on how to upload a list sample for optimization.
x-api-version: '2.0'
parameters:
- name: optimizerId
in: path
required: true
schema:
type: integer
example: '1'
- name: include_zero
in: query
required: false
schema:
type: string
example: '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/inbox/optimizer/{optimizerId}/domains/{domainId}:
get:
operationId: listOptimizerDomainsByList
summary: Domains by List
tags:
- Inbox Placement
description: Domains by List provides a full breakdown of domain distribution from your mailing list sample.
x-api-version: '2.0'
parameters:
- name: optimizerId
in: path
required: true
schema:
type: integer
example: '1'
- name: domainId
in: path
required: true
schema:
type: integer
example: '1'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
meta:
type: object
results:
type: array
items:
type: object
properties:
id:
type: integer
domain:
type: string
size:
type: integer
examples:
Domains by List:
value:
meta: {}
results:
- id: 1
domain: gmail.com
size: 201247
- id: 2
domain: googlemail.com
size: 43
'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/inbox/tests:
get:
operationId: inboxTestsAllInboxTests
summary: All Inbox Tests
tags:
- Inbox Placement
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
page: {}
limit: {}
enddate:
type: string
ip: {}
spfdomain: {}
dkimdomain: {}
region_id: {}
pages:
type: integer
total:
type: integer
results:
type: array
items:
type: object
properties:
id:
type: integer
created:
type: string
subject:
type: string
xheader:
type: object
properties:
key:
type: string
value:
type: string
from:
type: string
friendlyfrom:
type: string
seeds:
type: object
properties:
inbox:
type: integer
spam:
type: integer
missing:
type: integer
placement:
type: object
properties:
inbox:
type: number
spam:
type: number
missing:
type: number
authentication:
type: object
properties:
spf:
type: number
dkim:
type: integer
dmarc:
type: integer
status:
type: string
mtr:
type: number
overage:
type: boolean
examples:
All Inbox Tests:
value:
meta:
params:
startdate: '2021-01-01T05:00:00+00:00'
page: null
limit: null
enddate: '1970-01-01T00:00:00+00:00'
ip: null
spfdomain: null
dkimdomain: null
region_id: null
pages: 1
total: 1
results:
- id: 1
created: '2021-01-03 18:02:45'
subject: Inbox Test 1
xheader:
key: X-250ok-CID
value: '1111.2222'
from: from@domain.com
friendlyfrom: Your Friendly From
seeds:
inbox: 781
spam: 101
missing: 14
placement:
inbox: 87.2
spam: 11.3
missing: 1.5
authentication:
spf: 96.9
dkim: 100
dmarc: 100
status: processing
mtr: 2.6
overage: false
'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/inbox/tests/{testId}:
get:
operationId: inboxTestsInboxTestByID
summary: Inbox Test by ID
tags:
- Inbox Placement
x-api-version: '2.0'
parameters:
- name: testId
in: path
required: true
schema:
type: integer
example: '1'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
meta:
type: object
results:
type: object
properties:
id:
type: integer
created:
type: string
subject:
type: string
xheader:
type: object
properties:
key:
type: string
value:
type: string
from:
type: string
friendlyfrom:
type: string
seeds:
type: object
properties:
inbox:
type: integer
spam:
type: integer
missing:
type: integer
placement:
type: object
properties:
inbox:
type: number
spam:
type: number
missing:
type: number
authentication:
type: object
properties:
spf:
type: number
dkim:
type: integer
dmarc:
type: integer
status:
type: string
mtr:
type: number
overage:
type: string
examples:
Inbox Test by ID:
value:
meta: {}
results:
id: 1
created: '2021-01-01 09:16:54'
subject: 'Inbox Test #1'
xheader:
key: X-250ok-CID
value: '1111.2222'
from: from@domain.com
friendlyfrom: Acme Co.
seeds:
inbox: 791
spam: 100
missing: 5
placement:
inbox: 88.3
spam: 11.2
missing: 0.5
authentication:
spf: 97.1
dkim: 100
dmarc: 100
status: processing
mtr: 8.6
# --- truncated at 32 KB (142 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/return-path/refs/heads/main/openapi/return-path-inbox-placement-api-openapi.yml