List stats

Counts the org's mail over a range: sent, delivered, opened, clicked, bounced, complained and unsubscribed, each a count of messages, in all, by provider, by campaign and by day or hour (UTC).

GET /v1/email/stats

Email → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/email/stats`
Method	`GET`
Operation	`get_email_stats`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Counts the org's mail over a range: sent, delivered, opened, clicked, bounced, complained and unsubscribed, each a count of messages, in all, by provider, by campaign and by day or hour (UTC). Mail sent around this API, from the org's own tools on its SES or SendGrid account, is counted from the providers' events like mail sent through it.

GET /v1/email/stats

Request

5 fields.

Field	In	Type	Required	Description
`since`	query	string	—	Since is where the range starts, RFC 3339, rounded down to its day or hour.
`until`	query	string	—	Until is where the range ends, RFC 3339, rounded up to its day or hour.
`interval`	query	string	—	Interval is day (default, at most 400 days) or hour (at most 31 days), in UTC.
`provider`	query	string	—	Provider counts one rail only: ses or sendgrid.
`campaign`	query	string	—	Campaign counts one campaign only.

Response

Status	Body	Meaning
`200`	email.Stats	ok
`default`	problem-details	refused

200 body — 43 fields.

Field	In	Type	Always	Description
`campaign`	body	string	—	Campaign is the one campaign counted, when the request named one.
`campaigns`	body	email.Part[]	—	Campaigns is the range by campaign, the most sent first, at most 200; empty when the request named a campaign.
`campaigns[].name`	body	string	—	Name is the provider (ses, sendgrid) or the campaign.
`campaigns[].tally`	body	email.Tally	—
`campaigns[].tally.bounced`	body	integer (int64)	—	Bounced is messages that bounced, hard or soft (SendGrid's dropped included).
`campaigns[].tally.clicked`	body	integer (int64)	—	Clicked is messages a link of which was clicked.
`campaigns[].tally.complained`	body	integer (int64)	—	Complained is messages reported as spam.
`campaigns[].tally.delivered`	body	integer (int64)	—	Delivered is messages the receiving server took.
`campaigns[].tally.opened`	body	integer (int64)	—	Opened is messages opened.
`campaigns[].tally.sent`	body	integer (int64)	—	Sent is messages the provider accepted.
`campaigns[].tally.unsubscribed`	body	integer (int64)	—	Unsubscribed is messages whose recipient unsubscribed at the provider.
`interval`	body	string	—	Interval is day or hour: the step of Series.
`provider`	body	string	—	Provider is the one rail counted, when the request named one.
`providers`	body	email.Part[]	—	Providers is the range by provider.
`providers[].name`	body	string	—	Name is the provider (ses, sendgrid) or the campaign.
`providers[].tally`	body	email.Tally	—
`providers[].tally.bounced`	body	integer (int64)	—	Bounced is messages that bounced, hard or soft (SendGrid's dropped included).
`providers[].tally.clicked`	body	integer (int64)	—	Clicked is messages a link of which was clicked.
`providers[].tally.complained`	body	integer (int64)	—	Complained is messages reported as spam.
`providers[].tally.delivered`	body	integer (int64)	—	Delivered is messages the receiving server took.
`providers[].tally.opened`	body	integer (int64)	—	Opened is messages opened.
`providers[].tally.sent`	body	integer (int64)	—	Sent is messages the provider accepted.
`providers[].tally.unsubscribed`	body	integer (int64)	—	Unsubscribed is messages whose recipient unsubscribed at the provider.
`series`	body	email.Point[]	—	Series is every day or hour of the range in order, empty ones included.
`series[].at`	body	string (date-time)	—	At is the start of the day or hour, UTC.
`series[].tally`	body	email.Tally	—
`series[].tally.bounced`	body	integer (int64)	—	Bounced is messages that bounced, hard or soft (SendGrid's dropped included).
`series[].tally.clicked`	body	integer (int64)	—	Clicked is messages a link of which was clicked.
`series[].tally.complained`	body	integer (int64)	—	Complained is messages reported as spam.
`series[].tally.delivered`	body	integer (int64)	—	Delivered is messages the receiving server took.
`series[].tally.opened`	body	integer (int64)	—	Opened is messages opened.
`series[].tally.sent`	body	integer (int64)	—	Sent is messages the provider accepted.
`series[].tally.unsubscribed`	body	integer (int64)	—	Unsubscribed is messages whose recipient unsubscribed at the provider.
`since`	body	string (date-time)	—	Since is the start of the range, UTC.
`totals`	body	email.Tally	—
`totals.bounced`	body	integer (int64)	—	Bounced is messages that bounced, hard or soft (SendGrid's dropped included).
`totals.clicked`	body	integer (int64)	—	Clicked is messages a link of which was clicked.
`totals.complained`	body	integer (int64)	—	Complained is messages reported as spam.
`totals.delivered`	body	integer (int64)	—	Delivered is messages the receiving server took.
`totals.opened`	body	integer (int64)	—	Opened is messages opened.
`totals.sent`	body	integer (int64)	—	Sent is messages the provider accepted.
`totals.unsubscribed`	body	integer (int64)	—	Unsubscribed is messages whose recipient unsubscribed at the provider.
`until`	body	string (date-time)	—	Until is the end of the range, UTC, not included.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo email stats

.ts

.py

.go

.rs

.java

import { Configuration, EmailApi } from 'hanzoai';

const api = new EmailApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getEmailStats();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import EmailApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = EmailApi(client).get_email_stats()

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.EmailAPI.GetEmailStats(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, email_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = email_api::get_email_stats(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.EmailApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new EmailApi(client).getEmailStats();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

curl https://api.hanzo.ai/v1/email/stats \
  -H "Authorization: Bearer $HANZO_API_KEY"

MCP reaches email through the email tool, which names its 8 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_emails"
         }
       }
     }'

Email API · All Hanzo APIs · Interactive reference

Was this page useful?

Broken link or missing step? Drop it in #docs on Discord or open a PR.

PreviousList status — GET /v1/email/ses/status NextList email