Instantly Inbox Placement Analytics API
Analytics data for individual emails in inbox placement tests
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
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.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/instantly-ai-inboxplacementanalytics-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
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 Specification
openapi: 3.2.0
info:
title: Explorer Inbox Placement Analytics API
description: The entire API V2 documentation is interactive and can be tested here. To the right side of every endpoint you will see a box with an example request. You can click on the "Try it" button to send a request to the server right from the docs. You will need to provide an API key by clicking the `ApiKeyAuth_token` blue text.
version: 2.0.0
servers:
- url: https://api.instantly.ai
description: Instantly API Server
security:
- ApiKeyAuth: []
tags:
- name: InboxPlacementAnalytics
description: Analytics data for individual emails in inbox placement tests
x-group: Inbox Placement Analytics
paths:
/api/v2/inbox-placement-analytics:
get:
operationId: listInboxPlacementAnalytics
summary: List inbox placement analytics
tags:
- InboxPlacementAnalytics
description: 'Requires one of the following scopes: `inbox_placement_analytics:read`, `inbox_placement_analytics:all`, `all:read`, `all:all`'
parameters:
- schema:
type: integer
minimum: 1
maximum: 100
example: 10
example: 10
in: query
name: limit
required: false
description: The number of items to return
- schema:
type: string
example: 01956fbd-0eb1-72db-a565-82977a586084
example: 01956fbd-0eb1-72db-a565-82977a586084
in: query
name: starting_after
required: false
description: The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response.
- schema:
type: string
format: uuid
example: 019ffad2-9c10-7031-b800-4c42ddf964b4
example: 019ffad2-9c10-7031-b800-4c42ddf964b4
in: query
name: test_id
required: true
- schema:
type: string
example: '2026-08-13T11:12:14.352Z'
example: '2026-08-13T11:12:14.352Z'
in: query
name: date_from
required: false
- schema:
type: string
example: '2026-08-13T11:12:14.352Z'
example: '2026-08-13T11:12:14.352Z'
in: query
name: date_to
required: false
- schema:
type: string
example: 1,2
example: 1,2
in: query
name: recipient_geo
required: false
description: A comma-separated list of recipient geo values.
- schema:
type: string
example: 1,2
example: 1,2
in: query
name: recipient_type
required: false
description: A comma-separated list of recipient type values.
- schema:
type: string
example: 1,2
example: 1,2
in: query
name: recipient_esp
required: false
description: A comma-separated list of recipient ESP values.
- schema:
type: string
example: john@doe.com
example: john@doe.com
in: query
name: sender_email
required: false
responses:
'200':
description: The list of Inbox Placement Analytics
content:
application/json:
schema:
type: object
properties:
items:
type: array
description: The list of Inbox Placement Analytics
items:
$ref: '#/components/schemas/InboxPlacementAnalytics'
next_starting_after:
type: string
examples:
- 019ffad2-9c10-7031-b800-4c432391ac4d
- '2026-08-13T11:12:14.352Z'
description: The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API
example: 019ffad2-9c10-7031-b800-4c432391ac4d
additionalProperties: false
required:
- items
'401':
description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 401
examples:
- 401
example: 401
error:
type: string
enum:
- Unauthorized
examples:
- Unauthorized
example: Unauthorized
message:
type: string
examples:
- Missing Authorization header
example: Missing Authorization header
required:
- statusCode
- error
- message
'402':
description: This request cannot be fulfilled because the workspace does not have an active paid plan
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 402
examples:
- 402
example: 402
error:
type: string
enum:
- Payment Required
examples:
- Payment Required
example: Payment Required
message:
type: string
examples:
- Workspace does not have an active paid plan
example: Workspace does not have an active paid plan
required:
- statusCode
- error
- message
'404':
description: The requested resource was not found
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 404
examples:
- 404
example: 404
error:
type: string
enum:
- Not Found
examples:
- Not Found
example: Not Found
message:
type: string
examples:
- Resource not found
example: Resource not found
required:
- statusCode
- error
- message
'429':
description: You have exceeded the rate limit. Please check the rate limit docs for more information.
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 429
examples:
- 429
example: 429
error:
type: string
enum:
- Too Many Requests
examples:
- Too Many Requests
example: Too Many Requests
message:
type: string
examples:
- Rate limit exceeded
example: Rate limit exceeded
required:
- statusCode
- error
- message
/api/v2/inbox-placement-analytics/{id}:
get:
operationId: getInboxPlacementAnalytics
summary: Get inbox placement analytics
tags:
- InboxPlacementAnalytics
description: 'Requires one of the following scopes: `inbox_placement_analytics:read`, `inbox_placement_analytics:all`, `all:read`, `all:all`'
parameters:
- schema:
type: string
format: uuid
example: 019ffad2-9c11-761e-8be7-8204f980e956
example: 019ffad2-9c11-761e-8be7-8204f980e956
in: path
name: id
required: true
description: The ID of the requested item
responses:
'200':
description: The requested Inbox Placement Analytics
content:
application/json:
schema:
$ref: '#/components/schemas/InboxPlacementAnalytics'
'401':
description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 401
examples:
- 401
example: 401
error:
type: string
enum:
- Unauthorized
examples:
- Unauthorized
example: Unauthorized
message:
type: string
examples:
- Missing Authorization header
example: Missing Authorization header
required:
- statusCode
- error
- message
'402':
description: This request cannot be fulfilled because the workspace does not have an active paid plan
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 402
examples:
- 402
example: 402
error:
type: string
enum:
- Payment Required
examples:
- Payment Required
example: Payment Required
message:
type: string
examples:
- Workspace does not have an active paid plan
example: Workspace does not have an active paid plan
required:
- statusCode
- error
- message
'404':
description: The requested resource was not found
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 404
examples:
- 404
example: 404
error:
type: string
enum:
- Not Found
examples:
- Not Found
example: Not Found
message:
type: string
examples:
- Resource not found
example: Resource not found
required:
- statusCode
- error
- message
'429':
description: You have exceeded the rate limit. Please check the rate limit docs for more information.
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 429
examples:
- 429
example: 429
error:
type: string
enum:
- Too Many Requests
examples:
- Too Many Requests
example: Too Many Requests
message:
type: string
examples:
- Rate limit exceeded
example: Rate limit exceeded
required:
- statusCode
- error
- message
/api/v2/inbox-placement-analytics/stats-by-test-id:
post:
operationId: getInboxPlacementAnalyticsStatsByTestId
summary: Retrieve inbox placement analytics stats by test id
tags:
- InboxPlacementAnalytics
description: 'Provides aggregated inbox, spam and category counts for specified test IDs
Requires one of the following scopes: `inbox_placement_analytics:read`, `inbox_placement_analytics:all`, `all:read`, `all:all`'
requestBody:
content:
application/json:
schema:
type: object
properties:
test_ids:
type: array
items:
type: string
format: uuid
example: 019ffad2-9c11-761e-8be7-8205dfb9980e
minItems: 1
date_from:
type: string
example: '2026-08-13T11:12:14.353Z'
date_to:
type: string
example: '2026-08-13T11:12:14.353Z'
recipient_geo:
type: array
items:
type: number
enum:
- 1
- 2
- 3
- 4
x-enumDescriptions:
'1': United States
'2': Italy
'3': Germany
'4': France
example: 1
example:
- 1
recipient_type:
type: array
items:
type: number
enum:
- 1
- 2
x-enumDescriptions:
'1': Professional
'2': Personal
example: 1
example:
- 1
recipient_esp:
type: array
items:
type: number
enum:
- 1
- 2
- 8
- 12
- 13
x-enumDescriptions:
'1': Google
'2': Microsoft
'8': AirMail
'12': Web.de
'13': Libero.it
example: 1
example:
- 1
- 2
sender_email:
type: string
example: john@doe.com
required:
- test_ids
required: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: array
items:
type: object
properties:
test_id:
type: string
format: uuid
example: 019ffad2-9c11-761e-8be7-8206b9663293
count:
type: number
example: 1
spam_count:
type: number
example: 1
spam_percent:
type: number
example: 1
inbox_count:
type: number
example: 1
inbox_percent:
type: number
example: 1
category_count:
type: number
example: 1
category_percent:
type: number
example: 1
required:
- test_id
- count
- spam_count
- spam_percent
- inbox_count
- inbox_percent
- category_count
- category_percent
'401':
description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 401
examples:
- 401
example: 401
error:
type: string
enum:
- Unauthorized
examples:
- Unauthorized
example: Unauthorized
message:
type: string
examples:
- Missing Authorization header
example: Missing Authorization header
required:
- statusCode
- error
- message
'402':
description: This request cannot be fulfilled because the workspace does not have an active paid plan
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 402
examples:
- 402
example: 402
error:
type: string
enum:
- Payment Required
examples:
- Payment Required
example: Payment Required
message:
type: string
examples:
- Workspace does not have an active paid plan
example: Workspace does not have an active paid plan
required:
- statusCode
- error
- message
'404':
description: The requested resource was not found
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 404
examples:
- 404
example: 404
error:
type: string
enum:
- Not Found
examples:
- Not Found
example: Not Found
message:
type: string
examples:
- Resource not found
example: Resource not found
required:
- statusCode
- error
- message
'429':
description: You have exceeded the rate limit. Please check the rate limit docs for more information.
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 429
examples:
- 429
example: 429
error:
type: string
enum:
- Too Many Requests
examples:
- Too Many Requests
example: Too Many Requests
message:
type: string
examples:
- Rate limit exceeded
example: Rate limit exceeded
required:
- statusCode
- error
- message
/api/v2/inbox-placement-analytics/deliverability-insights:
post:
operationId: getInboxPlacementAnalyticsDeliverabilityInsights
summary: Retrieve inbox placement analytics deliverability insights
tags:
- InboxPlacementAnalytics
description: 'Provides deliverability insights for a specific inbox placement test
Requires one of the following scopes: `inbox_placement_analytics:read`, `inbox_placement_analytics:all`, `all:read`, `all:all`'
requestBody:
content:
application/json:
schema:
type: object
properties:
test_id:
type: string
format: uuid
example: 019ffad2-9c12-7627-a335-4988c0aa83fd
date_from:
type: string
example: '2026-08-13T11:12:14.354Z'
date_to:
type: string
example: '2026-08-13T11:12:14.354Z'
previous_date_from:
type: string
example: '2026-08-13T11:12:14.354Z'
previous_date_to:
type: string
example: '2026-08-13T11:12:14.354Z'
show_previous:
type: boolean
example: true
recipient_geo:
type: array
items:
type: number
enum:
- 1
- 2
- 3
- 4
x-enumDescriptions:
'1': United States
'2': Italy
'3': Germany
'4': France
example: 1
example:
- 1
recipient_type:
type: array
items:
type: number
enum:
- 1
- 2
x-enumDescriptions:
'1': Professional
'2': Personal
example: 1
example:
- 1
recipient_esp:
type: array
items:
type: number
enum:
- 1
- 2
- 8
- 12
- 13
x-enumDescriptions:
'1': Google
'2': Microsoft
'8': AirMail
'12': Web.de
'13': Libero.it
example: 1
example:
- 1
- 2
required:
- test_id
required: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: array
items:
type: object
properties:
test_id:
type: string
format: uuid
example: 019ffad2-9c12-7627-a335-49891053917b
from:
type:
- 'null'
- string
example: '2024-01-01'
to:
type:
- 'null'
- string
example: '2024-01-01'
previous_from:
type:
- 'null'
- string
example: '2023-01-01'
previous_to:
type:
- 'null'
- string
example: '2023-01-01'
sender_esp:
type: number
enum:
- 1
- 2
- 8
- 12
- 13
x-enumDescriptions:
'1': Google
'2': Microsoft
'8': AirMail
'12': Web.de
'13': Libero.it
example: 1
recipient_esp:
type: number
enum:
- 1
- 2
- 8
- 12
- 13
x-enumDescriptions:
'1': Google
'2': Microsoft
'8': AirMail
'12': Web.de
'13': Libero.it
example: 1
spam_percentage:
type:
- 'null'
- number
example: 10
inbox_percentage:
type:
- 'null'
- number
example: 20
category_percentage:
type:
- 'null'
- number
example: 70
prev_spam_percentage:
type:
- 'null'
- number
example: 10
prev_inbox_percentage:
type:
- 'null'
- number
example: 56.67
prev_category_percentage:
type:
- 'null'
- number
example: 33.33
'401':
description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 401
examples:
- 401
example: 401
error:
type: string
enum:
- Unauthorized
examples:
- Unauthorized
example: Unauthorized
message:
type: string
examples:
- Missing Authorization header
example: Missing Authorization header
required:
- statusCode
- error
- message
'402':
description: This request cannot be fulfilled because the workspace does not have an active paid plan
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 402
examples:
- 402
example: 402
error:
type: string
enum:
- Payment Required
examples:
- Payment Required
example: Payment Required
message:
type: string
examples:
- Workspace does not have an active paid plan
example: Workspace does not have an active paid plan
required:
- statusCode
- error
- message
'404':
description: The requested resource was not found
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 404
examples:
- 404
example: 404
error:
type: string
enum:
- Not Found
examples:
- Not Found
example: Not Found
message:
type: string
examples:
- Resource not found
example: Resource not found
required:
- statusCode
- error
- message
'429':
description: You have exceeded the rate limit. Please check the rate limit docs for more information.
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 429
examples:
- 429
example: 429
error:
type: string
enum:
- Too Many Requests
examples:
- Too Many Requests
example: Too Many Requests
message:
type: string
examples:
- Rate limit exceeded
example: Rate limit exceeded
required:
- statusCode
- error
- message
/api/v2/inbox-placement-analytics/stats-by-date:
post:
operationId: getInboxPlacementAnalyticsStatsByDate
summary: Get inbox placement analytics stats by date
tags:
- InboxPlacementAnalytics
description: 'Provides a time series representing the distribution of emails sent to inbox, spam, or category folders for scheduled inbox placement tests.
Requires one of the following scopes: `inbox_placement_analytics:read`, `inbox_placement_analytics:all`, `all:read`, `all:all`'
requestBody:
content:
application/json:
schema:
type: object
properties:
test_id:
type: string
format: uuid
example: 019ffad2-9c13-7365-81db-d29875d4a700
date_from:
type: string
example: '2026-08-13T11:12:14.355Z'
date_to:
type: string
example: '2026-08-13T11:12:14.355Z'
recipient_geo:
type: array
items:
type: number
enum:
- 1
- 2
- 3
- 4
x-enumDescriptions:
'1': United States
'2': Italy
'3': Germany
'4': France
example: 1
example:
- 1
recipient_type:
type: array
items:
type: number
enum:
- 1
- 2
x-enumDescriptions:
'1': Professional
'2': Personal
example: 1
example:
- 1
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/instantly-ai/refs/heads/main/openapi/instantly-ai-inboxplacementanalytics-api-openapi.yml