Docs / API reference

Analytics

Deliverability totals by provider, quota usage and the event log.

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

Delivery, engagement and failover analytics

GET /v1/analytics/summary

Totals, rates, a time series and a per-provider breakdown (latency, top error codes). Filter by provider (provider id or connection id, comma separated), sending domain, tag, template and time range (default last 30 days).

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

Parameters

NameInTypeDescription
fromquerystring
untilquerystring
providerquerystring
domainquerystring
tagquerystring
templatequerystring
intervalquery"hour" | "day"Default "day".

Responses

200 Success

{
  "totals": {
    "sent": number,
    "delivered": number,
    "bounced": number,
    "complained": number,
    "opened": number,
    "clicked": number,
    "failed": number,
    "failovers": number
  },
  "rates": {
    "delivery": number,
    "bounce": number,
    "complaint": number,
    "open": number,
    "click": number,
    "failover": number
  },
  "series": [{
    "sent": number,
    "delivered": number,
    "bounced": number,
    "complained": number,
    "opened": number,
    "clicked": number,
    "failed": number,
    "failovers": number,
    "t": string
  }],
  "byProvider": [{
    "sent": number,
    "delivered": number,
    "bounced": number,
    "complained": number,
    "opened": number,
    "clicked": number,
    "failed": number,
    "failovers": number,
    "connectionId": string,
    "provider": string,
    "name": string,
    "avgLatencyMs": number or null,
    "topErrors": [{ … }]
  }],
  "timezone": string
}
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)

Pooled and per-provider quota for today

GET /v1/analytics/quota

Includes a naive forecast of when today's pooled quota runs out at the current pace.

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

Responses

200 Success

{
  "pooled": {
    "dailyLimit": number or null,
    "usedToday": number,
    "remainingToday": number or null,
    "forecastExhaustAt": string or null,
    "excluded": [{
      "connectionId": string,
      "name": string,
      "reason": "sandbox" | "paused" | "error",
      "usedToday": number
    }]
  },
  "connections": [{
    "connectionId": string,
    "provider": string,
    "name": string,
    "dailyLimit": number or null,
    "usedToday": number,
    "monthlyLimit": number or null,
    "usedThisMonth": number,
    "health": number,
    "status": string
  }]
}
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)

Event log

GET /v1/events

Every lifecycle event (queued, sent, delivered, bounced, failover, opened, received, …), newest first.

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

Parameters

NameInTypeDescription
typequerystring
messageIdquerystring
providerquerystring
fromquerystring (date-time)
cursorquerystring
limitqueryintegerDefault 100. 1 to 500.

Responses

200 Success

{
  "data": [{
    "id": string,
    "type": string,
    "messageId": string or null,
    "provider": string or null,
    "connectionId": string or null,
    "recipient": string or null,
    "data": object or null,
    "occurredAt": string
  }],
  "nextCursor": string or null
}
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)