Docs / API reference

Security

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

Security alerts not acknowledged yet

GET /v1/security/alerts

Workspace owners, signed in. The security alerts of the last 30 days (API keys created, rotated, revoked or leaked, configuration changed or a new address used by a key, inbox rules sending mail outside the workspace, hourly digests) that this owner has not acknowledged. delivery says how each one reached the owners: email (the workspace's providers), instance (the server's alert mailer, ONESEND_ALERT_SMTP_URL) or dashboard (no email could be sent: only here).

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

Responses

200 Success

{
  "data": [{
    "id": string,
    "kind": string,
    "subject": string,
    "lines": [string],
    "delivery": "email" | "instance" | "dashboard",
    "createdAt": 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)

Acknowledge the security alerts

POST /v1/security/alerts/acknowledge

Workspace owners, signed in (not API keys): hides the alerts listed by GET /v1/security/alerts until a new one arrives.

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

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)