Skip to content
Pidgely Docs

Guides

Metrics

Sent, delivered, bounces, complaints, opens, clicks and their rates, by day, domain, tag, template, broadcast and mailbox provider. Every definition, the metrics API and the bounce and complaint alerts.

View as Markdown

Pidgely counts every send and every event as it happens: deliveries, bounces, complaints, delays, opens, clicks and unsubscribes. You read the numbers in the dashboard's Metrics page or with GET /metrics, for any range of up to 400 days, by day or broken down by domain, tag, template, broadcast or mailbox provider.

Counters

Field Counts
sent Recipients accepted for delivery (suppressed addresses excluded)
delivered Deliveries accepted by the receiving server
hard_bounced Permanent bounces; the address is suppressed
soft_bounced Transient and undetermined bounces (mailbox full, message too large, content rejected), and deliveries given up after 72 hours of retries
complained Spam complaints (not-spam reports are not counted)
delayed Deliveries delayed at least once (counted once per recipient)
suppressed Recipients skipped because they are on the suppression list
failed Deliveries that failed for another reason (account suspended, content expired)
unsubscribed One-click and link unsubscribes
opens Every recorded open, machine opens included
machine_opens Opens flagged as machine opens (Apple Mail Privacy Protection, image proxy prefetch, scanners)
unique_opens Recipients who opened at least once
unique_human_opens Recipients with at least one human (not machine) open
clicks Every recorded click, bot clicks included
bot_clicks Clicks flagged as bot clicks (security scanners, HEAD requests, many links at once)
unique_clicks Recipients who clicked at least once
unique_human_clicks Recipients with at least one human (not bot) click

Opens and clicks need open and click tracking on the sending domain or the send.

Rates

Rates are numbers between 0 and 1. A rate is null when its denominator is 0.

Field Formula
delivery_rate delivered / sent
bounce_rate hard_bounced / (delivered + hard_bounced), the rate mailbox providers and the reputation guard judge
soft_bounce_rate soft_bounced / sent
complaint_rate complained / delivered
open_rate unique_human_opens / delivered
raw_open_rate unique_opens / delivered (machine opens included, comparable with tools that do not filter them)
click_rate unique_human_clicks / delivered
click_to_open_rate unique_human_clicks / unique_human_opens
unsubscribe_rate unsubscribed / delivered

Breakdowns

group_by One point per Notes
day (default) UTC day of the range, zeros included
domain Sending domain label is the domain name
tag Tag, as name:value Up to 10 tags of an email are counted
template Template the email was sent from label is the template name
broadcast (or campaign) Broadcast label is the broadcast name
provider Recipient mailbox provider: gmail, outlook, yahoo, icloud, other From the address domain (gmail.com, hotmail.com.br, yahoo.co.uk, icloud.com…). Custom domains hosted at Google Workspace, Microsoft 365, Yahoo or iCloud are recognised from the MX host reached by the first delivery attempt.

Values are listed most sent first, at most 100. A filter narrows the result to one value and then always groups by day: pass one of domain_id, tag (name:value), template_id, broadcast_id or provider.

The API

cURL
curl -X GET 'https://api.pidgely.com/metrics?days=30&group_by=provider' \
  -H "Authorization: Bearer $PIDGELY_API_KEY"
Parameter Description
days The last N UTC days, today included (default 30, at most 400)
from, to A range of UTC days (YYYY-MM-DD) instead of days; at most 400 days
group_by day, domain, tag, template, broadcast, campaign or provider
domain_id, tag, template_id, broadcast_id, provider One filter
JSON
{
  "object": "metrics",
  "from": "2026-09-21",
  "to": "2026-10-20",
  "group_by": "provider",
  "filter": null,
  "totals": { "key": "total", "sent": 1200, "delivered": 1188, "hard_bounced": 7, "complained": 0, "unique_human_opens": 455, "unique_human_clicks": 131, "open_rate": 0.383, "click_rate": 0.1103, "bounce_rate": 0.0059, "…": "…" },
  "data": [
    { "key": "gmail", "sent": 640, "delivered": 636, "open_rate": 0.41, "…": "…" },
    { "key": "outlook", "sent": 310, "delivered": 305, "open_rate": 0.33, "…": "…" }
  ],
  "alerts": [],
  "thresholds": { "bounce_rate_warning": 0.04, "complaint_rate_warning": 0.0008, "bounce_rate_limit": 0.04, "complaint_rate_limit": 0.001 }
}

Every point has all the counters and all the rates.

GET /metrics/links lists the links of a broadcast (broadcast_id) or template (template_id), most clicked by people first, with clicks, bot_clicks, unique_clicks and unique_human_clicks, plus the all-time totals of that broadcast or template:

cURL
curl -X GET 'https://api.pidgely.com/metrics/links?broadcast_id=0199d7f6-4c8d-7e1a-9b3f-2d6a5c0e7f19' \
  -H "Authorization: Bearer $PIDGELY_API_KEY"

One email

List the events of an email returns its whole timeline and, per recipient, opens, human_opens, clicks, human_clicks, the first and last open and click, and the mailbox_provider.

Alerts

Mailbox providers start filtering senders well before anything visibly breaks. alerts warns when the range's rates cross their thresholds:

Metric warning above critical above
bounce_rate 4% the reputation guard's pause limit (4% by default)
complaint_rate 0.08% (Gmail and Yahoo's bulk sender limit is 0.3%; they recommend staying under 0.1%) the reputation guard's pause limit (0.1% by default)
JSON
{ "metric": "complaint_rate", "level": "warning", "rate": 0.0011, "threshold": 0.0008 }

Alerts need some volume to mean anything: bounce alerts start at 50 delivered or bounced messages, complaint alerts at 100 delivered. For comparison, Amazon SES reviews accounts at 5% bounces and 0.1% complaints. The reputation guard pauses sending on its own 7-day window; the dashboard shows the same warnings on the Overview and Metrics pages.

How the numbers are kept

  • Counters are updated by the same transaction that records each event, in daily rollups per dimension. Reading metrics never scans your emails, so it costs the same for ten emails or ten million.
  • Days are UTC and an event counts on the day it happened: an email sent on Monday and opened on Tuesday adds to Monday's sent and Tuesday's opens. Rates over a range are therefore more meaningful than rates of a single day.
  • Rollups are kept for 400 days, with the message metadata. They contain no addresses and no personal data.

In the dashboard

Metrics (under Sending) shows the counters and rates of the last 7, 30 or 90 days, the daily sends and engagement charts, breakdowns by domain, mailbox provider, tag, template and broadcast, and the alerts. The Overview shows the key rates of the period, and each email's page shows its full timeline: every open and click, bounce and complaint detail.