Inbox Placement

Read Inbox Placement results: where your emails land (inbox, tabs or spam) across Gmail, Outlook and Yahoo, and your senders' reputation.

get /inbox-placement/insights Deliverability insights get /inbox-placement/runs List inbox placement runs get /inbox-placement/runs/{id} Get an inbox placement run get /inbox-placement/runs/{id}/results List a run's individual probes get /inbox-placement/sender-reputation Sender reputation and health get /inbox-placement/stats-by-date Inbox placement stats by date get /inbox-placement/tests List inbox placement tests

Deliverability insights

get https://api.emailchaser.com/r/inbox-placement/insights

Works with a read-only key

What is wrong across the workspace right now, worst first, each with the action that fixes it. Combines the placement measured over the window with the latest health check of every connected mailbox: authentication records, blacklist listings and measured placement per mailbox.

Parameters

days integer in query
How many days of runs to summarise (1..365, default 30)

Responses

200 The findings · InboxPlacementInsightsResponse
401 Unauthorized - invalid or missing API key · ErrorUnauthorized
403 The workspace does not hold the Inbox Placement add-on (code inbox_placement_required) · InboxPlacementForbiddenResponse
500 Failed to build the insights · ErrorResponse

Fields in the 200 response

findings array of InboxPlacementFindingResponse
6 fields inside findings
- action string
  Action is what to do about it. Every finding has one: a report that only says what is wrong makes the reader's day worse without improving their delivery.
  Example: Publish a DMARC record. Start with p=none to observe, then move to quarantine.
- detail string
  Example: acme.com publishes no DMARC record.
- senderAddress string
  Example: tom@acme.com
- senderEmailId integer
  Example: 3
- severity string
  Severity is critical, warning or info.
  Example: critical
- title string
  Example: DMARC record missing
inboxRate integer
Example: 80
mailboxesAtRisk integer
Example: 2
mailboxesChecked integer
Example: 9
missingRate integer
Example: 3
providerBreakdown array of InboxPlacementProviderResponse
8 fields inside providerBreakdown
- inbox integer
  Example: 14
- inboxRate integer
  Example: 77
- label string
  Example: Gmail / Google Workspace
- missing integer
  Example: 0
- promotions integer
  Example: 2
- provider string
  Example: google
- seeds integer
  Example: 18
- spam integer
  Example: 2
runsInWindow integer
Example: 14
spamRate integer
Example: 12
windowDays integer
WindowDays is how far back the rates below were computed over.
Example: 30

Request

curl -X GET "https://api.emailchaser.com/r/inbox-placement/insights" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "findings": [
    {
      "action": "Publish a DMARC record. Start with p=none to observe, then move to quarantine.",
      "detail": "acme.com publishes no DMARC record.",
      "senderAddress": "tom@acme.com",
      "senderEmailId": 3,
      "severity": "critical",
      "title": "DMARC record missing"
    }
  ],
  "inboxRate": 80,
  "mailboxesAtRisk": 2,
  "mailboxesChecked": 9,
  "missingRate": 3,
  "providerBreakdown": [
    {
      "inbox": 14,
      "inboxRate": 77,
      "label": "Gmail / Google Workspace",
      "missing": 0,
      "promotions": 2,
      "provider": "google",
      "seeds": 18,
      "spam": 2
    }
  ],
  "runsInWindow": 14,
  "spamRate": 12,
  "windowDays": 30
}

List inbox placement runs

get https://api.emailchaser.com/r/inbox-placement/runs

Works with a read-only key

Lists inbox placement runs newest first, optionally filtered to one test with ?testId=. Counters on a run are only final once its status is completed. Note that every rate is -1 when nothing has been scored yet, which means NOT MEASURED and must not be rendered as 0%.

Parameters

testId integer in query
Only runs of this test
limit integer in query
How many runs to return (1..200, default 50)

Responses

200 The runs · InboxPlacementListResponse
401 Unauthorized - invalid or missing API key · ErrorUnauthorized
403 The workspace does not hold the Inbox Placement add-on (code inbox_placement_required) · InboxPlacementForbiddenResponse
500 Failed to load the runs · ErrorResponse

Fields in the 200 response

count integer
Example: 14
items array of InboxPlacementRunResponse
19 fields inside items
- completedAt string
- createdAt string
- error string
- failed integer
  Example: 0
- id integer
  Example: 481
- inbox integer
  Example: 96
- inboxRate integer
  InboxRate is the whole-percentage share of SCORED probes that reached the primary inbox. -1 when nothing has been scored.
  Example: 80
- messagesExpected integer
  Example: 120
- messagesSent integer
  Example: 120
- missing integer
  Missing counts probes never found in any folder, which usually means a silent block. Reported apart from spam because it is a worse problem with a different fix.
  Example: 4
- promotions integer
  Promotions counts every Gmail category tab: promotions, social and updates. Delivered, but filtered away from the reader.
  Example: 8
- seedsTargeted integer
  Example: 40
- sendersTargeted integer
  Example: 3
- spam integer
  Example: 12
- spamScore integer
  SpamScore is the content spam score in tenths of a point, so 47 is 4.7. -1 when not scored.
  Example: 12
- startedAt string
- status string
  Status is pending, sending, collecting, completed, failed or cancelled. Counters are only final once status is completed.
  Example: completed
- testId integer
  Example: 12
- trigger string
  Trigger is manual or scheduled.
  Example: scheduled

Request

curl -X GET "https://api.emailchaser.com/r/inbox-placement/runs" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "count": 14,
  "items": [
    {
      "completedAt": "string",
      "createdAt": "string",
      "error": "string",
      "failed": 0,
      "id": 481,
      "inbox": 96,
      "inboxRate": 80,
      "messagesExpected": 120,
      "messagesSent": 120,
      "missing": 4,
      "promotions": 8,
      "seedsTargeted": 40,
      "sendersTargeted": 3,
      "spam": 12,
      "spamScore": 12,
      "startedAt": "string",
      "status": "completed",
      "testId": 12,
      "trigger": "scheduled"
    }
  ]
}

Get an inbox placement run

get https://api.emailchaser.com/r/inbox-placement/runs/{id}

Works with a read-only key

Returns one run with its complete report: the headline split, the per-provider and per-sending-mailbox breakdowns, and the content spam rules the copy triggered. "Promotions" rolls up every Gmail category tab. "Missing" means the probe was never found in any folder, which usually indicates a silent block, and is reported apart from spam because it is a worse problem with a different fix.

Parameters

id integer required in path
Run ID

Responses

200 The run and its report · InboxPlacementRunDetailResponse
401 Unauthorized - invalid or missing API key · ErrorUnauthorized
403 The workspace does not hold the Inbox Placement add-on (code inbox_placement_required) · InboxPlacementForbiddenResponse
404 No such run in this workspace · ErrorResponse
500 Failed to load the run · ErrorResponse

Fields in the 200 response

completedAt string
createdAt string
error string
failed integer
Example: 0
id integer
Example: 481
inbox integer
Example: 96
inboxRate integer
InboxRate is the whole-percentage share of SCORED probes that reached the primary inbox. -1 when nothing has been scored.
Example: 80
messagesExpected integer
Example: 120
messagesSent integer
Example: 120
missing integer
Missing counts probes never found in any folder, which usually means a silent block. Reported apart from spam because it is a worse problem with a different fix.
Example: 4
promotions integer
Promotions counts every Gmail category tab: promotions, social and updates. Delivered, but filtered away from the reader.
Example: 8
providerBreakdown array of InboxPlacementProviderResponse
8 fields inside providerBreakdown
- inbox integer
  Example: 14
- inboxRate integer
  Example: 77
- label string
  Example: Gmail / Google Workspace
- missing integer
  Example: 0
- promotions integer
  Example: 2
- provider string
  Example: google
- seeds integer
  Example: 18
- spam integer
  Example: 2
seedsTargeted integer
Example: 40
senderBreakdown array of InboxPlacementSenderResponse
9 fields inside senderBreakdown
- failed integer
  Example: 0
- inbox integer
  Example: 31
- inboxRate integer
  Example: 77
- missing integer
  Example: 1
- promotions integer
  Example: 2
- senderAddress string
  Example: tom@acme.com
- senderEmailId integer
  Example: 3
- sent integer
  Example: 40
- spam integer
  Example: 6
sendersTargeted integer
Example: 3
spam integer
Example: 12
spamScore integer
SpamScore is the content spam score in tenths of a point, so 47 is 4.7. -1 when not scored.
Example: 12
spamScoreRules array of InboxPlacementSpamRuleResponse
4 fields inside spamScoreRules
- advice string
  Example: Write the subject in sentence case.
- description string
  Example: The subject line is in capitals.
- name string
  Example: SUBJECT_ALL_CAPS
- points integer
  Points is the rule's cost in tenths of a point, so 15 is 1.5 points.
  Example: 15
startedAt string
status string
Status is pending, sending, collecting, completed, failed or cancelled. Counters are only final once status is completed.
Example: completed
testId integer
Example: 12
trigger string
Trigger is manual or scheduled.
Example: scheduled

Request

curl -X GET "https://api.emailchaser.com/r/inbox-placement/runs/123" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "completedAt": "string",
  "createdAt": "string",
  "error": "string",
  "failed": 0,
  "id": 481,
  "inbox": 96,
  "inboxRate": 80,
  "messagesExpected": 120,
  "messagesSent": 120,
  "missing": 4,
  "promotions": 8,
  "providerBreakdown": [
    {
      "inbox": 14,
      "inboxRate": 77,
      "label": "Gmail / Google Workspace",
      "missing": 0,
      "promotions": 2,
      "provider": "google",
      "seeds": 18,
      "spam": 2
    }
  ],
  "seedsTargeted": 40,
  "senderBreakdown": [
    {
      "failed": 0,
      "inbox": 31,
      "inboxRate": 77,
      "missing": 1,
      "promotions": 2,
      "senderAddress": "tom@acme.com",
      "senderEmailId": 3,
      "sent": 40,
      "spam": 6
    }
  ],
  "sendersTargeted": 3,
  "spam": 12,
  "spamScore": 12,
  "spamScoreRules": [
    {
      "advice": "Write the subject in sentence case.",
      "description": "The subject line is in capitals.",
      "name": "SUBJECT_ALL_CAPS",
      "points": 15
    }
  ],
  "startedAt": "string",
  "status": "completed",
  "testId": 12,
  "trigger": "scheduled"
}

List a run's individual probes

get https://api.emailchaser.com/r/inbox-placement/runs/{id}/results

Works with a read-only key

Returns one row per probe: which of your mailboxes sent it, which seed mailbox received it, where it landed and how long it took to arrive. deliverySeconds is worth watching on its own: greylisting and throttling show up there before they show up in a placement number.

Parameters

id integer required in path
Run ID

Responses

200 The probes · InboxPlacementResultListResponse
401 Unauthorized - invalid or missing API key · ErrorUnauthorized
403 The workspace does not hold the Inbox Placement add-on (code inbox_placement_required) · InboxPlacementForbiddenResponse
404 No such run in this workspace · ErrorResponse
500 Failed to load the results · ErrorResponse

Fields in the 200 response

count integer
Example: 120
items array of InboxPlacementResultResponse
9 fields inside items
- deliverySeconds integer
  DeliverySeconds is how long the probe took to appear. -1 when never detected. A slow delivery is itself a signal: greylisting and throttling both show up here before they show up in a placement number.
  Example: 46
- detectedAt string
- error string
- id integer
  Example: 90211
- placement string
  Placement is pending, inbox, spam, promotions, social, updates, missing or failed.
  Example: inbox
- seedAddress string
  Example: seed-104@example.net
- seedProvider string
  Example: google
- senderAddress string
  Example: tom@acme.com
- sentAt string
runId integer
Example: 481

Request

curl -X GET "https://api.emailchaser.com/r/inbox-placement/runs/123/results" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "count": 120,
  "items": [
    {
      "deliverySeconds": 46,
      "detectedAt": "string",
      "error": "string",
      "id": 90211,
      "placement": "inbox",
      "seedAddress": "seed-104@example.net",
      "seedProvider": "google",
      "senderAddress": "tom@acme.com",
      "sentAt": "string"
    }
  ],
  "runId": 481
}

Sender reputation and health

get https://api.emailchaser.com/r/inbox-placement/sender-reputation

Works with a read-only key

The latest health check for every connected mailbox: SPF, DKIM, DMARC and MX status, blacklist listings with their delisting links, measured inbox placement, and a combined 0-100 health score. blacklistsChecked is reported next to blacklistsListed so the count can never be read as a total. A placementScore or healthScore of -1 means not measured, not zero.

Responses

200 The mailbox health table · SenderReputationListResponse
401 Unauthorized - invalid or missing API key · ErrorUnauthorized
403 The workspace does not hold the Inbox Placement add-on (code inbox_placement_required) · InboxPlacementForbiddenResponse
500 Failed to load the mailbox health · ErrorResponse

Fields in the 200 response

count integer
Example: 9
items array of SenderReputationResponse
16 fields inside items
- blacklistListings array of BlacklistListingResponse
- blacklistsChecked integer
  BlacklistsChecked is how many zones were queried, reported next to the listing count so the number can never be read as a total.
  Example: 23
- blacklistsListed integer
  Example: 1
- checkedAt string
- dkimStatus string
  Example: OK
- dmarcPolicy string
  Example: quarantine
- dmarcStatus string
  Example: MISSING
- dnsIssues array of string
- domain string
  Example: acme.com
- healthScore integer
  HealthScore is 0-100 combining placement, authentication and blacklist standing. -1 when it cannot be computed.
  Example: 71
- mxStatus string
  Example: OK
- placementScore integer
  PlacementScore is the inbox rate over recent completed runs. -1 when the mailbox has never been tested.
  Example: 77
- senderAddress string
  Example: tom@acme.com
- senderEmailId integer
  Example: 3
- sendingIp string
  SendingIP is empty for mailboxes on a shared provider (Gmail, Microsoft), which have no dedicated IP of their own to check.
  Example: 203.0.113.5
- spfStatus string
  Each status is OK, WARNING, MISSING or ERROR.
  Example: OK

Request

curl -X GET "https://api.emailchaser.com/r/inbox-placement/sender-reputation" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "count": 9,
  "items": [
    {
      "blacklistListings": [
        {
          "answer": "127.0.0.2",
          "delistUrl": "https://check.spamhaus.org/",
          "kind": "ip",
          "name": "Spamhaus ZEN",
          "reason": "On the SBL: the IP is on Spamhaus's main spam-source list.",
          "txt": "string",
          "value": "203.0.113.5",
          "zone": "zen.spamhaus.org"
        }
      ],
      "blacklistsChecked": 23,
      "blacklistsListed": 1,
      "checkedAt": "string",
      "dkimStatus": "OK",
      "dmarcPolicy": "quarantine",
      "dmarcStatus": "MISSING",
      "dnsIssues": [
        "string"
      ],
      "domain": "acme.com",
      "healthScore": 71,
      "mxStatus": "OK",
      "placementScore": 77,
      "senderAddress": "tom@acme.com",
      "senderEmailId": 3,
      "sendingIp": "203.0.113.5",
      "spfStatus": "OK"
    }
  ]
}

Inbox placement stats by date

get https://api.emailchaser.com/r/inbox-placement/stats-by-date

Works with a read-only key

Rolls completed runs up by UTC calendar day over a window, for a trend chart. Days on which nothing ran are ABSENT from the series rather than returned as zeros: a zero-filled day plots as placement collapsing to 0%, which reads as an outage when it means nobody ran a test. Defaults to the last 30 days.

Parameters

from string in query
Start of the window, RFC3339. Defaults to 30 days ago.
to string in query
End of the window, RFC3339. Defaults to now.

Responses

200 The daily series · InboxPlacementStatsByDateResponse
400 Malformed or reversed date range · ErrorResponse
401 Unauthorized - invalid or missing API key · ErrorUnauthorized
403 The workspace does not hold the Inbox Placement add-on (code inbox_placement_required) · InboxPlacementForbiddenResponse
500 Failed to load the history · ErrorResponse

Fields in the 200 response

days array of InboxPlacementDailyStatResponse
7 fields inside days
- date string
  Date is the UTC day.
- inbox integer
  Example: 180
- inboxRate integer
  Example: 81
- missing integer
  Example: 4
- promotions integer
  Example: 12
- runs integer
  Example: 2
- spam integer
  Example: 24
from string
to string

Request

curl -X GET "https://api.emailchaser.com/r/inbox-placement/stats-by-date" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "days": [
    {
      "date": "string",
      "inbox": 180,
      "inboxRate": 81,
      "missing": 4,
      "promotions": 12,
      "runs": 2,
      "spam": 24
    }
  ],
  "from": "string",
  "to": "string"
}

List inbox placement tests

get https://api.emailchaser.com/r/inbox-placement/tests

Works with a read-only key

Lists every inbox placement test defined in the workspace, newest first. A test is the definition (content, which mailboxes to send from, and for a recurring test how often); each execution is a run, listed separately at /inbox-placement/runs.

Responses

200 The workspace's tests · InboxPlacementTestListResponse
401 Unauthorized - invalid or missing API key · ErrorUnauthorized
403 The workspace does not hold the Inbox Placement add-on (code inbox_placement_required) · InboxPlacementForbiddenResponse
500 Failed to load the tests · ErrorResponse

Fields in the 200 response

count integer
Example: 3
items array of InboxPlacementTestResponse
11 fields inside items
- createdAt string
- id integer
  Example: 12
- intervalHours integer
  IntervalHours is how often a recurring test repeats. Null for one-time.
  Example: 24
- isPaused boolean
  Example: false
- kind string
  Kind is one_time or recurring.
  Example: recurring
- lastRunAt string
- name string
  Example: Q3 outbound - main sequence
- nextRunAt string
- seedProviders array of string
  SeedProviders restricts the seed panel. Empty means every provider.
  Example: ["google","microsoft"]
- senderEmailIds array of integer
  SenderEmailIDs are the mailboxes the test sends from.
  Example: [1,2,3]
- subject string
  Example: Question about your onboarding flow

Request

curl -X GET "https://api.emailchaser.com/r/inbox-placement/tests" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "count": 3,
  "items": [
    {
      "createdAt": "string",
      "id": 12,
      "intervalHours": 24,
      "isPaused": false,
      "kind": "recurring",
      "lastRunAt": "string",
      "name": "Q3 outbound - main sequence",
      "nextRunAt": "string",
      "seedProviders": [
        "google",
        "microsoft"
      ],
      "senderEmailIds": [
        1,
        2,
        3
      ],
      "subject": "Question about your onboarding flow"
    }
  ]
}

Generated from the Emailchaser API's own OpenAPI definition, so it always matches the running API.

Inbox Placement

Deliverability insights#

Parameters

Responses

List inbox placement runs#

Parameters

Responses

Get an inbox placement run#

Parameters

Responses

List a run's individual probes#

Parameters

Responses

Sender reputation and health#

Responses

Inbox placement stats by date#

Parameters

Responses

List inbox placement tests#

Responses

Deliverability insights

List inbox placement runs

Get an inbox placement run

List a run's individual probes

Sender reputation and health

Inbox placement stats by date

List inbox placement tests