# Analytics examples

Each example answers one question. It gives the query as JSON and a prompt for an [AI assistant](/platform/analytics/mcp). 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](/platform/analytics/query#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?

```json
{
  "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?

```json
{
  "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:

```json
{
  "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?

```json
{
  "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:

```json
{
  "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?

```json
{
  "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?

```json
{
  "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](/platform/emails/tags) with the name `campaign` on your email.

```json
{
  "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?

```json
{
  "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?

```json
{
  "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](/api-reference/team). 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`.

```json
{
  "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](/platform/analytics/dimensions#from-address-and-subject).

## Next steps

- [Query analytics with the API](/platform/analytics/query). Learn each field of a query.
- [Metrics](/platform/analytics/metrics) and [Dimensions](/platform/analytics/dimensions). Look up a name or a rule.