Skip to main content
Start with the campaign summary to see how many messages bounced and which causes were identified. Filter its recipient messages by a cause, then inspect the diagnostic for an individual send. Event queries give you a separate view of occurrences, unique-contact counts, and trends.

​
Before you begin

Use a project secret API key with the project editor role or higher. The campaign must belong to that project. Set SPOTZEE_API_KEY to the key and CAMPAIGN_ID to the campaign identifier in these examples.

​
Read totals and causes

Read delivery.bounced for the number of messages in the bounced state. delivery.bounce_categories splits that total across the 12 categories. delivery.classification_coverage reports classified, unclassified, and total bounced messages. Repeated sends to the same contact are separate messages. The summary can be reused for 30 seconds. delivery.calculated_at records when it was calculated. Delivery processing can add further delay before an outcome appears. Compare timestamps when reconciling a summary with freshly requested message details.

​
Find affected messages

bounce_category selects bounced messages with that cause. Use bounce_category=unknown for unclassified bounces, including historical messages with no recognised stored category. Without a cause filter, segment accepts all, sent, opened, or bounced. The response has one row per message, including repeated sends to the same contact. Read bounce_classification for its diagnostic, severity, finality, and evidence reason; it can be null when no valid classification is stored. email is the destination recorded for that send and can be null when the original destination was not retained. Pages default to 25 messages, with a maximum of 100. They sort by send_at descending, with contact and reference identifiers breaking ties. Use direction=asc for ascending order. Pass next or prev as the next request’s cursor, retaining the same filters and direction. These cursor field names differ from the Events API’s nextCursor and prevCursor.

​
Category identifiers and UI labels

Use the identifier in API filters. The UI displays its corresponding label: Unclassified means the available evidence does not identify a cause. It does not mean the message was delivered. Classification coverage depends on the delivery path and retained evidence; other configured providers do not have the same guaranteed classification coverage as managed delivery.

​
Reconcile message and event reports

A bounced-message report describes message outcomes. Event queries describe occurrences during a time window. One message can have several temporary failure events before its final outcome, and email_failed can include a submission failure. The resulting counts answer different questions and need not match. Historical events can receive response-only enrichment from retained evidence. That does not rewrite stored events or fill missing classifications on campaign messages. Keep unclassified messages in your totals, and use the diagnostic evidence before deciding whether to retry or correct contact details. See the generated Campaigns reference in the Main API for complete campaign and recipient response contracts.