Analytics

Analytics examples

Each example answers one question. It gives the query as JSON and a prompt for an AI assistant. The two give the same numbers.

Pass the fields of the query to the analytics method of an SDK, or send them as the body of POST /v1/analytics. See Write a query with an SDK for the form in each language.

Change the dates before you use a query. A window can go back as far as meta.available_since.

Check the health of your email each week

Question. How did delivery go this week, and is it better or worse than last week?

Code
{
  "metrics": ["delivered", "delivery_rate", "bounce_rate", "deferral_rate", "complaint_rate"],
  "from": "2026-11-04",
  "to": "2026-11-10",
  "timezone": "Europe/Amsterdam",
  "compare": "previous_period"
}

For the team Acme, give the delivery rate, bounce rate, deferral rate, and complaint rate of 4 to 10 November in Amsterdam time. Compare with the 7 days before.

Read the result. Look at change first. For a rate, percentage_points is the difference that you can say out loud: "the bounce rate went up by 0.3 points". Then look at rate_bases. A large change on a small number of recipients is noise.

Find the provider that defers your email

Question. Which mailbox provider slows down or refuses your email?

Code
{
  "metrics": ["delivery_attempts", "delivered", "deferred_events", "deferral_rate", "bounced"],
  "from": "2026-11-10",
  "to": "2026-11-10",
  "include": ["breakdown"],
  "group_by": ["provider_family"],
  "sort": { "metric": "deferred_events", "direction": "desc" },
  "limit": 10
}

Which mailbox providers deferred our email on 10 November? Show the delivery attempts, the deferrals, the deferral rate, and the bounces for each provider. Sort by the number of deferrals.

Read the result. A provider with many deferrals and few bounces accepts your email, but slowly. A provider where the bounces go up with the deferrals refuses your email.

The query sorts by the count, not by the rate. A sort by rate puts small providers with three recipients at the top.

To see when the problem started, filter on the provider and ask for hourly buckets:

Code
{
  "metrics": ["delivery_attempts", "deferral_rate"],
  "from": "2026-11-10",
  "to": "2026-11-10",
  "include": ["time_series"],
  "interval": "hour",
  "filters": [
    { "dimension": "provider_family", "operator": "eq", "values": ["Microsoft"] }
  ]
}

Find out why email bounces

Question. What do receiving servers say when they refuse your email?

Code
{
  "metrics": ["bounced", "deferred_events"],
  "from": "2026-11-04",
  "to": "2026-11-10",
  "include": ["breakdown"],
  "group_by": ["smtp_response_group"],
  "sort": { "metric": "bounced", "direction": "desc" },
  "limit": 10
}

What are the ten most frequent SMTP replies behind our bounces from 4 to 10 November? Show the number of bounces and deferrals for each reply.

Read the result. Each row is one reply, with addresses and IDs replaced by placeholders:

Code
{
  "dimensions": { "smtp_response_group": "550 5.1.1 The email account that you tried to reach does not exist. <session_id> - gsmtp" },
  "metrics": { "bounced": 184, "deferred_events": 0 }
}

For a shorter list of causes, group by bounce_classification. For the causes at one provider, add a filter on provider_family.

Find the recipient domains with the most bounces

Question. Which domains do the bounces come from?

Code
{
  "metrics": ["bounced", "transport_outcome_recipients", "bounce_rate"],
  "from": "2026-11-04",
  "to": "2026-11-10",
  "include": ["breakdown"],
  "group_by": ["recipient_domain"],
  "sort": { "metric": "bounced", "direction": "desc" },
  "limit": 20
}

Show the 20 recipient domains with the most bounces from 4 to 10 November. For each domain, give the bounces, the recipients with a final result, and the bounce rate.

Read the result. Look for a domain with many recipients and a bounce rate close to 1. It is often a spelling error in a signup form, such as gmial.com.

Measure how fast your email arrives

Question. How long does delivery take, and when is it slow?

Code
{
  "metrics": ["total_latency_p50_ms", "total_latency_p95_ms", "total_latency_p99_ms", "total_latency_samples"],
  "from": "2026-11-10",
  "to": "2026-11-10",
  "timezone": "Europe/Amsterdam",
  "include": ["summary", "time_series"],
  "interval": "hour"
}

Show the median, the 95th percentile, and the 99th percentile of the total delivery time for each hour of 10 November, in Amsterdam time. Give the times in seconds.

Read the result. The values are in milliseconds. total_latency is the time from acceptance until delivery. If p50 is low and p99 is high, most email is fast and a small part waits. That part is usually deferred email. Group by provider_family with the delivery_latency metrics to find the provider.

Compare campaigns with a tag

Question. Which campaign has the most bounces and complaints?

This example needs a tag with the name campaign on your email.

Code
{
  "metrics": ["delivered", "bounce_rate", "complaint_rate", "unsubscribed"],
  "from": "2026-11-01",
  "to": "2026-11-10",
  "include": ["breakdown"],
  "group_by": ["tag:campaign"],
  "sort": { "metric": "delivered", "direction": "desc" }
}

Group by the tag campaign for 1 to 10 November. Show the delivered recipients, the bounce rate, the complaint rate, and the unsubscribes.

Read the result. Each row is one value of the tag. Email without the tag is not in the breakdown.

Open and click metrics are not available with a tag. To compare the opens of two campaigns, send them through different routes and group by route_id.

Separate human opens from machine opens

Question. How many recipients read your email, and how many opens come from machines?

Code
{
  "metrics": ["open_tracked_delivered", "human_opens", "human_open_rate", "privacy_opens", "scanner_opens"],
  "from": "2026-11-04",
  "to": "2026-11-10",
  "include": ["summary", "breakdown"],
  "group_by": ["provider_family"],
  "sort": { "metric": "open_tracked_delivered", "direction": "desc" }
}

From 4 to 10 November, how many recipients had a human open? Show the human open rate, the privacy proxy opens, and the security scanner opens for each mailbox provider.

Read the result. human_open_rate uses only the email that had open tracking on. A provider with many privacy_opens hides the behavior of its users. For those recipients, you cannot know if a person read the email.

A human open rate that is higher than 1 means that the window is too short. The opens belong to email that was delivered before the window.

Report on each project

Question. What did each project send, day by day?

Code
{
  "metrics": ["accepted", "delivered", "bounced"],
  "from": "2026-11-04",
  "to": "2026-11-10",
  "include": ["breakdown"],
  "group_by": ["project_id"],
  "include_trend": true
}

For each project, show the accepted, delivered, and bounced recipients for each day from 4 to 10 November. Use the project names.

Read the result. Each row has a trend with one bucket for each day. The API returns the project as an ID. Get the names from the projects endpoint. An AI assistant can look up the names for you.

Compare subject lines

Question. Which subject lines bounce the most?

This query uses personal data. The token needs read:analytics and read:messages.

Code
{
  "metrics": ["delivered", "bounced", "bounce_rate"],
  "from": "2026-11-04",
  "to": "2026-11-10",
  "timezone": "UTC",
  "include": ["breakdown"],
  "group_by": ["subject"],
  "sort": { "metric": "delivered", "direction": "desc" },
  "limit": 20
}

Show the 20 subject lines with the most delivered recipients from 4 to 10 November in UTC. Add the bounces and the bounce rate.

Read the result. A subject line that includes a name or an order number is different for each recipient. Each one then has its own row. This breakdown is useful for email with a fixed subject.

With an AI assistant, this query works only when personal-information filtering is off for the team. See From address and subject.

Next steps

Query analytics with the API. Learn each field of a query.
Metrics and Dimensions. Look up a name or a rule.

Dimensions Handle API tokens securely