Deliverability Investigation
Use credentials created in the region selected above. Changing the documentation region updates examples; it does not move your account or resources.
All responses use the standard WAPI envelope: { success: true, data: ... } or { success: false, error: { code, message } }.
Authenticate using a WAPI key in the X-Api-Key header. The key selects its workspace; domain and DNS read permissions do not grant access to deliverability data. X-Id is optional and, if supplied, must match the authenticated workspace account.
Use emailType to select transactional (default) or marketing. Use startTimestamp and endTimestamp as UTC ISO 8601 strings, for example 2026-10-20T00:00:00.000Z, not dates or Unix numbers. The start is inclusive and the end exclusive; the end cannot be in the future and the window cannot exceed 90 days. Summary and affected-recipient queries default to the preceding 24 hours; recipient investigation defaults to 30 days.
Lists accept limit from 1 to 50 (default 25). Pass the returned nextCursor as cursor, without changing the email type, recipient, event type or time window. On continuation, omit timestamps to retain the original window or repeat the exact original timestamps. An empty page may still have a continuation cursor; only null means finished.
Recipient investigation is a read-only POST. All its parameters, including recipientEmail, belong in the JSON body, never the URL. It sends no email and modifies no suppression. Summary counts refer to events received in the window; investigation totals refer to the latest stored outcomes of messages created in that window. These are different measures, and neither is a mailbox-provider reputation score.
- Get Summary for counts by event status and time window.
- List Affected Recipients for bounce, complaint, unsubscribe, or other affected recipients.
- Investigate Recipient for suppression state and recent message history.
Required permissions
Grant these existing permissions through the Web Setup API key or its API-key role. Existing keys are not automatically granted new access. No separate deliverability permission is required.
- Summary:
analytics:read. - Affected recipients:
email_event:readandemail_event_recipient:read. - Recipient investigation:
email_event:read,email_event_recipient:readandsuppression:read. - Optional diagnostics on detail responses:
email_event_diagnostics:read. Without it, fields such asdiagnosticCode,bounceSubTypeanderrorMessageare omitted. Email bodies and subjects are not returned.
Errors and completeness
The standard success envelope is { success: true, data: ... }. Errors use { success: false, error: { code, message } } with a non-2xx HTTP status. Invalid parameters return 400; missing key permissions return 403. API Gateway can reject an invalid key before the handler runs. A query that cannot finish within its 20-second/500-data-request budget returns 503 with the standard WAPI INTERNAL_ERROR and a sanitized message, not partial totals. Try a smaller time window; do not retry indefinitely.
Data reflects retained records and eventually consistent indexes, not an atomic historical snapshot. Late events or updated message outcomes may change later queries. Current suppression records can be scoped to a domain or subscription group; they are not a send-eligibility decision. Never bypass suppression or automatically resend based on an investigation.
The earlier draft names accountType, from, to, statuses, status and email are not accepted as aliases. Use the endpoint-specific names documented here. Existing portal and MCP request formats have not changed.

