Metrics and analytics

Email Service exposes analytics that allow you to inspect email sending performance and delivery rates across all your domains.

The metrics displayed in the Cloudflare dashboard ↗ charts are queried from Cloudflare's GraphQL Analytics API. You can access the metrics programmatically via GraphQL or HTTP client.

Email Service currently exposes the below metrics:

Metrics can be queried (and are retained) for the past 31 days.

Per-domain analytics for Email Service are available in the Cloudflare dashboard. To view current and historical metrics:

1. Log in to the Cloudflare dashboard ↗ and select your account.
2. Go to Compute > Email Service and select Email Sending or Email Routing.
3. Select an existing domain or view account-wide metrics.
4. Select the Analytics tab.

You can optionally select a time window to query. This defaults to the last 24 hours.

You can programmatically query analytics for your Email Service domains via the GraphQL Analytics API. This API queries the same datasets as the Cloudflare dashboard, and supports GraphQL introspection.

To get started using the GraphQL Analytics API, follow the documentation to setup Authentication for the GraphQL Analytics API. Your API token must include the Analytics Read permission.

These are zone-level datasets. To query them, provide your zone ID (not account ID) as the zoneTag filter. The GraphQL datasets for Email Service include:

• emailSendingAdaptiveGroups — aggregated email sending counts with groupable dimensions
• emailSendingAdaptive — individual email sending events
• emailRoutingAdaptiveGroups — aggregated email routing counts with groupable dimensions
• emailRoutingAdaptive — individual email routing events

The emailSendingAdaptiveGroups dataset supports the following dimensions for grouping and filtering:

The emailSendingAdaptive dataset includes all of the above plus per-event fields: from, to, subject, messageId, sessionId, errorDetail.

The emailRoutingAdaptiveGroups dataset supports the following dimensions for grouping and filtering:

The emailRoutingAdaptive dataset includes all of the above plus per-event fields: from, to, subject, messageId, sessionId, errorDetail, ruleMatched.

The following are common GraphQL queries that you can use to retrieve information about Email Service analytics. These queries use the variable $zoneTag, which should be set to your Cloudflare Zone ID. You can find this in the Cloudflare dashboard under your domain's Overview page.

{
	"zoneTag": "<YOUR_ZONE_ID>",
	"start": "2024-07-15",
	"end": "2024-07-30"
}

To query the count of emails for a given date range, grouped by date and status (for example, delivered, deliveryFailed):

query EmailSendingByStatus($zoneTag: string!, $start: Date!, $end: Date!) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			emailSendingAdaptiveGroups(
				filter: { date_geq: $start, date_leq: $end }
				limit: 10000
				orderBy: [date_DESC]
			) {
				count
				dimensions {
					date
					status
				}
			}
		}
	}
}

To investigate delivery failure causes for a specific date range, grouped by errorCause and sendingDomain:

query EmailDeliveryFailures($zoneTag: string!, $start: Date!, $end: Date!) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			emailSendingAdaptiveGroups(
				filter: { date_geq: $start, date_leq: $end, status: "deliveryFailed" }
				limit: 10000
				orderBy: [date_DESC]
			) {
				count
				dimensions {
					date
					errorCause
					sendingDomain
				}
			}
		}
	}
}

To query email sending volume grouped by hour, useful for identifying traffic patterns:

query EmailSendingHourlyVolume($zoneTag: string!, $start: Time!, $end: Time!) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			emailSendingAdaptiveGroups(
				filter: { datetimeHour_geq: $start, datetimeHour_leq: $end }
				limit: 10000
				orderBy: [datetimeHour_ASC]
			) {
				count
				dimensions {
					datetimeHour
					status
				}
			}
		}
	}
}

To query individual email events for troubleshooting specific delivery issues. This uses the emailSendingAdaptive dataset and filters by datetime (Time type):

query RecentEmailEvents($zoneTag: string!, $start: Time!, $end: Time!) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			emailSendingAdaptive(
				filter: { datetime_geq: $start, datetime_leq: $end }
				limit: 50
				orderBy: [datetime_DESC]
			) {
				datetime
				from
				to
				subject
				status
				eventType
				sendingDomain
				messageId
				errorCause
				errorDetail
				dkim
				dmarc
				spf
				isSpam
			}
		}
	}
}

To query the count of routed emails for a given date range, grouped by date and status:

query EmailRoutingByStatus($zoneTag: string!, $start: Date!, $end: Date!) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			emailRoutingAdaptiveGroups(
				filter: { date_geq: $start, date_leq: $end }
				limit: 10000
				orderBy: [date_DESC]
			) {
				count
				dimensions {
					date
					status
				}
			}
		}
	}
}

To see which routing rules are matching emails, grouped by ruleMatched and action:

query EmailRoutingRuleActivity($zoneTag: string!, $start: Date!, $end: Date!) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			emailRoutingAdaptiveGroups(
				filter: { date_geq: $start, date_leq: $end }
				limit: 10000
				orderBy: [date_DESC]
			) {
				count
				dimensions {
					date
					ruleMatched
					action
				}
			}
		}
	}
}

To query individual routing events for troubleshooting:

query RecentRoutingEvents($zoneTag: string!, $start: Time!, $end: Time!) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			emailRoutingAdaptive(
				filter: { datetime_geq: $start, datetime_leq: $end }
				limit: 50
				orderBy: [datetime_DESC]
			) {
				datetime
				from
				to
				subject
				status
				action
				ruleMatched
				messageId
				errorDetail
				dkim
				dmarc
				spf
				isSpam
			}
		}
	}
}

• Email logs — view individual email activity in the dashboard.
• Audit logs — track configuration changes.
• GraphQL Analytics API — full GraphQL API reference.