Docs / API reference

Admin

Instance administration for people listed in ONESEND_ADMIN_EMAILS: status page incidents and self-checks.

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

List status page incidents

GET /v1/admin/status-incidents

Instance admins only (ONESEND_ADMIN_EMAILS).

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

Responses

200 Success

{
  "data": [{
    "id": string,
    "title": string,
    "status": "investigating" | "identified" | "monitoring" | "resolved",
    "impact": "minor" | "major" | "critical",
    "components": [string],
    "updates": [{ … }],
    "createdAt": string,
    "updatedAt": string,
    "resolvedAt": 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)

Post a status page incident

POST /v1/admin/status-incidents

Instance admins only. Shown on /status while open, and under past incidents for 90 days after it is resolved. An open incident sets its components to degraded (minor impact) or down (major, critical).

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

Request body

application/json, required.

FieldTypeDescription
titlerequiredstring
bodyrequiredstringFirst update shown under the title
status"investigating" | "identified" | "monitoring" | "resolved"Default "investigating".
impact"minor" | "major" | "critical"Default "minor".
componentsarray of "api" | "sending" | "inbound" | "dashboard"Affected components (api, sending, inbound, dashboard); empty means all Default []. At most 10 items.

Responses

201 Success

{
  "id": string,
  "title": string,
  "status": "investigating" | "identified" | "monitoring" | "resolved",
  "impact": "minor" | "major" | "critical",
  "components": [string],
  "updates": [{
    "at": string,
    "status": string,
    "body": string
  }],
  "createdAt": string,
  "updatedAt": string,
  "resolvedAt": string or null
}
Errors: 400, 401, 403, 404, 409, 413, 415, 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)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Update a status page incident

PATCH /v1/admin/status-incidents/{id}

Instance admins only. Send body to add an update. Setting status: "resolved" closes the incident.

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

Parameters

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
titlestring
status"investigating" | "identified" | "monitoring" | "resolved"
impact"minor" | "major" | "critical"
componentsarray of "api" | "sending" | "inbound" | "dashboard"At most 10 items.
bodystringAdds an update with this text (and the new or current status)

Responses

200 Success

{
  "id": string,
  "title": string,
  "status": "investigating" | "identified" | "monitoring" | "resolved",
  "impact": "minor" | "major" | "critical",
  "components": [string],
  "updates": [{
    "at": string,
    "status": string,
    "body": string
  }],
  "createdAt": string,
  "updatedAt": string,
  "resolvedAt": string or null
}
Errors: 400, 401, 403, 404, 409, 413, 415, 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)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Delete a status page incident

DELETE /v1/admin/status-incidents/{id}

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

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

204 No content

Errors: 400, 401, 403, 404, 409, 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)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Run the status self-checks now

POST /v1/admin/status-checks/run

Instance admins only. Records one round of checks (as the 5-minute job does) and returns the results.

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

Responses

200 Success

{
  "data": [{
    "component": string,
    "status": string,
    "detail": string
  }]
}
Errors: 400, 401, 403, 404, 409, 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)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)