Retrieve email delivery metrics, engagement analytics, and geographic data via the NorthRelay API.

Analytics API

The Analytics API provides access to delivery metrics, engagement data, geographic breakdowns, and provider-level statistics. Use these endpoints to monitor your sending performance and optimize your email strategy.

Heatmap

Retrieve hourly engagement data across days of the week. Use this to identify the best times to send emails.

GET /analytics/heatmap

Query Parameters

Parameter	Type	Default	Description
`metric`	string	`opens`	Metric to plot: `opens`, `clicks`, `deliveries`
`from`	string	30 days ago	Start date (ISO 8601, e.g., `2026-03-01`)
`to`	string	today	End date (ISO 8601)
`timezone`	string	`UTC`	Timezone for hour bucketing (e.g., `America/Toronto`)

Example Request

curl "https://app.northrelay.ca/api/v1/analytics/heatmap?metric=opens&from=2026-03-01&to=2026-03-19&timezone=America/Toronto" \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx"

Example Response

{
  "metric": "opens",
  "from": "2026-03-01T00:00:00.000Z",
  "to": "2026-03-19T23:59:59.999Z",
  "timezone": "America/Toronto",
  "data": [
    { "day": 0, "hour": 9, "value": 142 },
    { "day": 0, "hour": 10, "value": 187 },
    { "day": 1, "hour": 9, "value": 156 },
    { "day": 1, "hour": 14, "value": 203 }
  ]
}

The day field is 0-indexed (0 = Sunday, 6 = Saturday). The hour field is 0--23 in the requested timezone.

Geographic

Retrieve engagement data broken down by country and optionally by region.

GET /analytics/geographic

Query Parameters

Parameter	Type	Default	Description
`metric`	string	`opens`	Metric: `opens`, `clicks`, `deliveries`
`from`	string	30 days ago	Start date (ISO 8601)
`to`	string	today	End date (ISO 8601)
`country`	string	--	Filter by ISO 3166-1 alpha-2 country code (e.g., `CA`, `US`)

Example Request

curl "https://app.northrelay.ca/api/v1/analytics/geographic?metric=opens&from=2026-03-01" \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx"

Example Response

{
  "metric": "opens",
  "from": "2026-03-01T00:00:00.000Z",
  "to": "2026-03-19T23:59:59.999Z",
  "data": [
    { "country": "CA", "countryName": "Canada", "value": 4521, "percentage": 42.3 },
    { "country": "US", "countryName": "United States", "value": 3890, "percentage": 36.4 },
    { "country": "GB", "countryName": "United Kingdom", "value": 891, "percentage": 8.3 },
    { "country": "DE", "countryName": "Germany", "value": 456, "percentage": 4.3 }
  ],
  "total": 10692
}

Providers

Retrieve delivery and engagement metrics broken down by email provider (Gmail, Outlook, Yahoo, etc.). Use this to identify deliverability issues with specific providers.

GET /analytics/providers

Query Parameters

Parameter	Type	Default	Description
`from`	string	30 days ago	Start date (ISO 8601)
`to`	string	today	End date (ISO 8601)
`limit`	integer	`10`	Number of top providers to return (max 50)

Example Request

curl "https://app.northrelay.ca/api/v1/analytics/providers?from=2026-03-01&limit=5" \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx"

Example Response

{
  "from": "2026-03-01T00:00:00.000Z",
  "to": "2026-03-19T23:59:59.999Z",
  "data": [
    {
      "provider": "Gmail",
      "domain": "gmail.com",
      "sent": 5200,
      "delivered": 5180,
      "bounced": 12,
      "opened": 2340,
      "clicked": 890,
      "complained": 2,
      "deliveryRate": 99.6,
      "openRate": 45.2,
      "clickRate": 17.2
    },
    {
      "provider": "Outlook",
      "domain": "outlook.com",
      "sent": 3100,
      "delivered": 3050,
      "bounced": 35,
      "opened": 1220,
      "clicked": 410,
      "complained": 5,
      "deliveryRate": 98.4,
      "openRate": 40.0,
      "clickRate": 13.4
    }
  ],
  "total": {
    "sent": 10692,
    "delivered": 10590,
    "bounced": 72,
    "opened": 4580,
    "clicked": 1620,
    "complained": 8
  }
}

Export

Export raw analytics data as CSV or JSON for external analysis.

GET /analytics/export

Query Parameters

Parameter	Type	Default	Description
`from`	string	30 days ago	Start date (ISO 8601)
`to`	string	today	End date (ISO 8601)
`format`	string	`json`	Export format: `json` or `csv`
`metrics`	string	all	Comma-separated metrics: `deliveries`, `bounces`, `opens`, `clicks`, `complaints`
`groupBy`	string	`day`	Aggregation period: `hour`, `day`, `week`, `month`
`categories`	string	--	Comma-separated categories to filter by

Example Request (JSON)

curl "https://app.northrelay.ca/api/v1/analytics/export?from=2026-03-01&to=2026-03-19&format=json&groupBy=day&metrics=deliveries,opens,clicks" \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx"

Example Response (JSON)

{
  "from": "2026-03-01T00:00:00.000Z",
  "to": "2026-03-19T23:59:59.999Z",
  "groupBy": "day",
  "data": [
    {
      "date": "2026-03-01",
      "deliveries": 520,
      "opens": 234,
      "clicks": 89
    },
    {
      "date": "2026-03-02",
      "deliveries": 480,
      "opens": 201,
      "clicks": 76
    }
  ]
}

Example Request (CSV)

curl "https://app.northrelay.ca/api/v1/analytics/export?from=2026-03-01&format=csv&groupBy=day" \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx" \
  -o analytics.csv

The CSV response includes a Content-Disposition: attachment; filename="analytics-export.csv" header. The first row contains column headers.

Summary

Get a high-level summary of your sending performance for a given period.

GET /analytics/summary

Query Parameters

Parameter	Type	Default	Description
`from`	string	30 days ago	Start date (ISO 8601)
`to`	string	today	End date (ISO 8601)

Example Request

curl "https://app.northrelay.ca/api/v1/analytics/summary?from=2026-03-01" \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx"

Example Response

{
  "from": "2026-03-01T00:00:00.000Z",
  "to": "2026-03-19T23:59:59.999Z",
  "totals": {
    "sent": 10692,
    "delivered": 10590,
    "bounced": 72,
    "deferred": 30,
    "opened": 4580,
    "uniqueOpens": 3210,
    "clicked": 1620,
    "uniqueClicks": 1140,
    "complained": 8,
    "unsubscribed": 15
  },
  "rates": {
    "deliveryRate": 99.0,
    "bounceRate": 0.7,
    "openRate": 42.8,
    "clickRate": 15.2,
    "clickToOpenRate": 35.5,
    "complaintRate": 0.07,
    "unsubscribeRate": 0.14
  },
  "quotaUsed": 10692,
  "quotaLimit": 50000,
  "quotaPercentage": 21.4
}

The rates object contains percentages. clickToOpenRate is clicks divided by opens (not by sends).

Metric Definitions

Metric	Definition
`sent`	Total emails submitted to the delivery queue
`delivered`	Emails accepted by the recipient mail server (2xx SMTP response)
`bounced`	Emails permanently rejected (5xx SMTP response)
`deferred`	Emails temporarily rejected; NorthRelay will retry automatically
`opened`	Total open events (includes repeat opens by the same recipient)
`uniqueOpens`	Distinct recipients who opened at least once
`clicked`	Total click events (includes repeat clicks)
`uniqueClicks`	Distinct recipients who clicked at least once
`complained`	Recipients who marked the email as spam
`unsubscribed`	Recipients who clicked the unsubscribe link
`deliveryRate`	`delivered / sent * 100`
`bounceRate`	`bounced / sent * 100`
`openRate`	`uniqueOpens / delivered * 100`
`clickRate`	`uniqueClicks / delivered * 100`
`clickToOpenRate`	`uniqueClicks / uniqueOpens * 100`
`complaintRate`	`complained / delivered * 100`
`unsubscribeRate`	`unsubscribed / delivered * 100`

Analytics API

Analytics APICopy Anchor Link

HeatmapCopy Anchor Link

Query ParametersCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

GeographicCopy Anchor Link

Query ParametersCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

ProvidersCopy Anchor Link

Query ParametersCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

ExportCopy Anchor Link

Query ParametersCopy Anchor Link

Example Request (JSON)Copy Anchor Link

Example Response (JSON)Copy Anchor Link

Example Request (CSV)Copy Anchor Link

SummaryCopy Anchor Link

Query ParametersCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

Metric DefinitionsCopy Anchor Link

On this page

Analytics API

Heatmap

Query Parameters

Example Request

Example Response

Geographic

Query Parameters

Example Request

Example Response

Providers

Query Parameters

Example Request

Example Response

Export

Query Parameters

Example Request (JSON)

Example Response (JSON)

Example Request (CSV)

Summary

Query Parameters

Example Request

Example Response

Metric Definitions