Docs / API reference

Statistics

Delivery and engagement statistics with filters.

Base URL https://your-server.example (your OneSend server). Authentication and errors are described in the overview.

Email statistics with filters and previous-period comparison

GET /v1/statistics/overview

Defaults to the last 30 days. previous holds the same rates for the period of equal length just before from. provider accepts provider ids (e.g. resend) or connection ids, comma separated.

Authentication: Authorization: Bearer with an API key or a session token.

Parameters

NameInTypeDescription
fromquerystring
untilquerystring
typequery"all" | "transactional" | "marketing"Default "all".
campaignIdquerystring
providerquerystring
domainquerystring
recipientDomainquerystring
tagquerystring
templateIdquerystring
intervalquery"hour" | "day" | "week"Bucket size. Days and weeks start at midnight in the workspace time zone. Ranges: hour ≤ 31 days, day ≤ 2 years, week ≤ 10 years. Default "day".

Responses

200 Success

{
  "totals": {
    "recipients": number,
    "sent": number,
    "delivered": number,
    "uniqueOpens": number,
    "opens": number,
    "uniqueClicks": number,
    "clicks": number,
    "hardBounces": number,
    "softBounces": number,
    "unsubscribes": number,
    "complaints": number,
    "conversions": number,
    "revenue": number
  },
  "rates": {
    "delivery": number,
    "open": number,
    "click": number,
    "clickToOpen": number,
    "bounce": number,
    "unsubscribe": number,
    "complaint": number,
    "conversion": number
  },
  "previous": {
    "delivery": number,
    "open": number,
    "click": number,
    "clickToOpen": number,
    "bounce": number,
    "unsubscribe": number,
    "complaint": number,
    "conversion": number
  },
  "series": [{
    "t": string,
    "sent": number,
    "delivered": number,
    "uniqueOpens": number,
    "uniqueClicks": number,
    "bounces": number,
    "unsubscribes": number,
    "conversions": number,
    "complaints": number
  }],
  "topCampaigns": [{
    "id": string,
    "name": string,
    "sentAt": string or null,
    "recipients": number,
    "openRate": number,
    "clickRate": number,
    "bounceRate": number,
    "conversionRate": number
  }],
  "byRecipientDomain": [{
    "domain": string,
    "sent": number,
  …
Errors: 400, 401, 403, 404, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Email by mailbox provider and by category

GET /v1/statistics/breakdown

Same filters as the overview (default last 30 days). byMailboxProvider groups recipients by their mailbox provider from the recipient domain (gmail.com and googlemail.com → google; outlook, hotmail, live and msn → outlook; yahoo, ymail and aol → yahoo; icloud, me and mac → apple; proton → proton; everything else → other). byCategory lists transactional email, each campaign and automation email.

Authentication: Authorization: Bearer with an API key or a session token.

Parameters

NameInTypeDescription
fromquerystring
untilquerystring
typequery"all" | "transactional" | "marketing"Default "all".
campaignIdquerystring
providerquerystring
domainquerystring
recipientDomainquerystring
tagquerystring
templateIdquerystring

Responses

200 Success

{
  "byMailboxProvider": [{
    "provider": "google" | "outlook" | "yahoo" | "apple" | "proton" | "other",
    "sent": number,
    "delivered": number,
    "uniqueOpens": number,
    "uniqueClicks": number,
    "bounced": number,
    "complaints": number,
    "rates": {
      "delivery": number,
      "open": number,
      "click": number,
      "bounce": number,
      "complaint": number
    }
  }],
  "byCategory": [{
    "kind": "transactional" | "campaign" | "automation",
    "campaignId": string or null,
    "name": string or null,
    "sent": number,
    "delivered": number,
    "uniqueOpens": number,
    "uniqueClicks": number,
    "bounced": number,
    "complaints": number,
    "rates": {
      "delivery": number,
      "open": number,
      "click": number,
      "bounce": number,
      "complaint": number
    }
  }]
}
Errors: 400, 401, 403, 404, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)