The Reputation API from Return Path — 18 operation(s) for reputation.
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-reputation-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 Reputation 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: Reputation
paths:
/2.0/reputation/blocklists:
get:
operationId: blocklistsBlocklists
summary: Blocklists
tags:
- Reputation
description: Returns a list of all supported blocklists. Blocklists can be filtered by type using the type=ip or type=domain query filters.
x-api-version: '2.0'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
rbl:
type: string
list:
type: string
label:
type: string
type:
type: string
url:
type: string
examples:
Get Blocklists Type IP:
value:
- id: 1
rbl: 0spam
list: DNSBL
label: 0spam - DNSBL
type: ip
url: http://0spam.fusionzero.com/
- id: 2
rbl: Barracuda
list: BRBL
label: Barracuda - BRBL
type: ip
url: http://www.barracudacentral.org/rbl
- id: 3
rbl: CASA
list: CBL
label: CASA - CBL
type: ip
url: http://www.anti-spam.org.cn
text/plain:
example: "{\n \"meta\": {\n \"params\": {\n \"type\": \"ip\"\n },\n \"total\": 61\n },\n \"results\": [\n {\n \"id\": 129,\n \"rbl\": \"0spam\",\n \"list\": \"DNSBL\",\n \"label\": \"0spam - DNSBL\",\n \"type\": \"ip\",\n \"url\": \"http://0spam.fusionzero.com/\"\n },\n {\n \"id\": 15,\n \"rbl\": \"Barracuda\",\n \"list\": \"BRBL\",\n \"label\": \"Barracuda - BRBL\",\n \"type\": \"ip\",\n \"url\": \"http://www.barracudacentral.org/rbl\"\n },\n {\n \"id\": 44,\n \"rbl\": \"CASA\",\n \"list\": \"CBL\",\n \"label\": \"CASA - CBL\",\n \"type\": \"ip\",\n \"url\": \"http://www.anti-spam.org.cn\"\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/reputation/blocklists/listings:
get:
operationId: blocklistsListings
summary: Listings
tags:
- Reputation
description: Returns a list active blacklist listings for your IPs, domains, profiles and providers. Additional resources are provided for each listing type.
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
page:
type: integer
limit:
type: integer
status:
type: string
next:
type: string
pages:
type: integer
total:
type: integer
results:
type: array
items:
type: object
properties:
status:
type: string
listing_date:
type: string
delisting_date:
type: string
listing:
type: object
properties:
id:
type: integer
item:
type: string
type:
type: string
blocklist:
type: object
properties:
id:
type: integer
rbl:
type: string
list:
type: string
label:
type: string
url:
type: string
profile:
type: object
properties:
id:
type: integer
name:
type: string
examples:
Get Blocklistings:
value:
meta:
params:
startdate: '2021-04-12T00:00:00+00:00'
enddate: '2021-05-12T00:00:00+00:00'
page: 1
limit: 500
status: all
next: /api/2.0/reputation/blocklists/listings?page=2&limit=500&startdate=2021-04-12&enddate=2021-05-12&status=all
pages: 1
total: 2
results:
- status: resolved
listing_date: '2021-05-10 19:16:10'
delisting_date: '2021-05-11 01:16:12'
listing:
id: 1
item: 127.0.0.1
type: ip
blocklist:
id: 8
rbl: SpamCop
list: SpamCop Blocking List
label: SpamCop - SpamCop Blocking List
url: https://www.spamcop.net/fom-serve/cache/76.html
profile:
id: 1
name: 'Profile #1'
- status: active
listing_date: '2021-05-10 17:47:59'
delisting_date: null
listing:
id: 1
item: 127.0.0.1
type: ip
blocklist:
id: 8
rbl: SpamCop
list: SpamCop Blocking List
label: SpamCop - SpamCop Blocking List
url: https://www.spamcop.net/fom-serve/cache/76.html
profile:
id: 1
name: 'Profile #1'
Get Blocklistings Current:
value:
meta:
params:
startdate: '2021-04-12T00:00:00+00:00'
enddate: '2021-05-12T00:00:00+00:00'
page: 1
limit: 500
status: all
next: /api/2.0/reputation/blocklists/listings?page=2&limit=500&startdate=2021-04-12&enddate=2021-05-12&status=all
pages: 1
total: 2
results:
- status: active
listing_date: '2021-05-10 17:47:59'
delisting_date: null
listing:
id: 1
item: 127.0.0.1
type: ip
blocklist:
id: 8
rbl: SpamCop
list: SpamCop Blocking List
label: SpamCop - SpamCop Blocking List
url: https://www.spamcop.net/fom-serve/cache/76.html
profile:
id: 1
name: 'Profile #1'
Get Blocklistings Resolved:
value:
meta:
params:
startdate: '2021-04-12T00:00:00+00:00'
enddate: '2021-05-12T00:00:00+00:00'
page: 1
limit: 500
status: all
next: /api/2.0/reputation/blocklists/listings?page=2&limit=500&startdate=2021-04-12&enddate=2021-05-12&status=all
pages: 1
total: 1
results:
- status: resolved
listing_date: '2021-05-10 19:16:10'
delisting_date: '2021-05-11 01:16:12'
listing:
id: 1
item: 127.0.0.1
type: ip
blocklist:
id: 8
rbl: SpamCop
list: SpamCop Blocking List
label: SpamCop - SpamCop Blocking List
url: https://www.spamcop.net/fom-serve/cache/76.html
profile:
id: 1
name: 'Profile #1'
'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/reputation/profiles:
get:
operationId: profilesProfiles
summary: Profiles
tags:
- Reputation
description: List current reputation profiles along with any blocklist hits and issue metrics.
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
items:
type: integer
enabled:
type: boolean
issues:
type: object
properties:
blocklistings:
type: integer
traps:
type: integer
rdns:
type: integer
senderscore:
type: integer
blocklists:
type: array
items:
type: object
properties:
id:
type: integer
label:
type: string
type:
type: string
examples:
Get Profiles:
value:
meta:
total: 27
results:
- id: 1
name: Validity Mail Servers
items: 25
enabled: true
issues:
blocklistings: 0
traps: 0
rdns: 16
senderscore: 99
blocklists:
- id: 1
label: SBL (Spamhaus SBL Data)
type: ip
- id: 2
label: SBL (Spamhaus SBL CSS Data)
type: ip
- id: 3
label: XBL (CBL Data)
type: ip
- id: 2
name: Test Profile (no blocklists selected)
items: 1
enabled: false
issues:
blocklistings: 0
traps: 0
rdns: 0
senderscore: 0
blocklists: []
'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: profilesCreateProfile
summary: Create Profile
tags:
- Reputation
description: 'Create a new reputation profile, specifying the type of blocklist to track or specific blocklist providers.
Available Fields
name Required, the name of this profile
type Optional, the type of blocklist to track. Must be one of all, ip or domain. If specified, blocklist_ids is ignored.
blocklist_ids Optional, IDs of specific blocklist providers. Provider IDs are available under the /reputation/blocklists resource.
One of the type or blocklist_ids fields must be specified.'
x-api-version: '2.0'
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
name:
type: string
type:
type: string
description: May be 'all', 'ip' or 'domain'.
example:
name: Profile Test 1
type: ip
responses:
'200':
description: OK
content:
text/plain:
example: response
'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/reputation/profiles/{profileId}:
get:
operationId: profilesProfileByID
summary: Profile by ID
tags:
- Reputation
description: Fetch data for a specific reputation profile along with any blocklist hits and issue metrics.
x-api-version: '2.0'
parameters:
- name: profileId
in: path
required: true
schema:
type: integer
example: '1'
responses:
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
Get Profile by ID Invalid Profile ID:
value:
error: The 'id' value must be numeric.
Get Profile by ID No Results Found:
value:
error: No Results Found
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
meta:
type: object
results:
type: object
properties:
id:
type: integer
name:
type: string
items:
type: integer
enabled:
type: boolean
issues:
type: object
properties:
blocklistings:
type: integer
traps:
type: integer
rdns:
type: integer
senderscore:
type: integer
blocklists:
type: array
items:
type: object
properties:
id:
type: integer
label:
type: string
type:
type: string
examples:
Get Profile by ID:
value:
meta: {}
results:
id: 1
name: Validity Mail Servers
items: 25
enabled: true
issues:
blocklistings: 0
traps: 0
rdns: 16
senderscore: 99
blocklists:
- id: 1
label: SBL (Spamhaus SBL Data)
type: ip
- id: 2
label: SBL (Spamhaus SBL CSS Data)
type: ip
- id: 3
label: XBL (CBL Data)
type: ip
'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'
'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: profilesUpdateProfile
summary: Update Profile
tags:
- Reputation
description: 'Update the blocklist IDs or type associated with a specified reputation profile.
Available Fields
name Optional, update the name of this profile
type Optional, replace type of blocklists to track. Must be one of all, ip or domain. If specified, blocklist_ids is ignored.
blocklist_ids Optional, replace the specific blocklist provider IDs associated with this profile. Provider IDs are available under the /reputation/blocklists resource.
One of the type or blocklist_ids fields must be specified.'
x-api-version: '2.0'
parameters:
- name: profileId
in: path
required: true
schema:
type: integer
example: '1'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
type: string
description: (Required) The profile's name.
type:
type: string
description: (Required if blocklists not set) May be 'all', 'ip' or 'domain'.
blocklists:
type: string
description: (Required if type not set) An array of blocklist ids.
enabled:
type: string
description: Whether or not the profile is enabled for monitoring. May be 0 or 1.
example:
name: Profile Updated 1
type: all
blocklists: 1,2,5
enabled: '1'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
type: string
id:
type: string
examples:
Update Profile Array of Blocklists ID:
value:
status: success
id: '1'
Update Profile Select All Blocklists:
value:
status: success
id: '1'
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
Update Profile Profile not found:
value:
error: Profile not found
'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'
'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: profilesDeleteProfile
summary: Delete Profile
tags:
- Reputation
description: Delete a specified profile. This action cannot be undone.
x-api-version: '2.0'
parameters:
- name: profileId
in: path
required: true
schema:
type: integer
example: '1'
responses:
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
Delete Profile Profile not found:
value:
error: Profile not found.
Delete Profile:
value:
status: success
id: 1
'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'
'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/reputation/profiles/{profileId}/items:
get:
operationId: profilesProfileItems
summary: Profile - Items
tags:
- Reputation
description: List all profile items for a specified reputation profile.
x-api-version: '2.0'
parameters:
- name: profileId
in: path
required: true
schema:
type: integer
example: '1'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
meta:
type: object
properties:
params:
type: object
properties:
type:
type: string
total:
type: integer
results:
type: array
items:
type: object
properties:
id:
type: integer
item:
type: string
type:
type: string
description:
type: string
senderscore:
type: integer
examples:
Get Profile Items Type ip:
value:
meta:
params:
type: ip
total: 2
results:
- id: 1
item: 127.0.0.1
type: ip
description: Utility Server 1
senderscore: 99
- id: 2
item: 127.0.0.2
type: ip
description: Utility Server 1
senderscore: 0
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
Get Profile Items Invalid Type:
value:
error: The 'type' value must equal 'cidr', 'domain_name', 'ip_range', 'ip' or 'shared_domain'.
Profile - Items Profile not found:
value:
error: Profile not found.
# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/return-path/refs/heads/main/openapi/return-path-reputation-api-openapi.yml