Docs / API reference

Public endpoints

Endpoints outside /v1: browser conversions, provider webhooks, inbound ingest and health. Most do not use an API key.

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

Record a conversion from a web page

POST /t/conversion

Called by /t/onesend.js (onesend.convert()). Authenticate with a Conversion tracking key (os_pub_…) in Authorization: Bearer. A conversion is attributed only through the os_ct click token that OneSend adds to campaign links; the response is the same whether or not anything was attributed. To attribute by email address or message id, call POST /v1/conversions from your server with a secret key. CORS allows any origin.

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

Request body

application/json, required.

FieldTypeDescription
tokenstringThe os_ct click token from the landing URL. onesend.token() returns it.
goalstring
valuenumber
currencystring
idempotencyKeystringFor example the order id. Repeated keys are recorded once.

Responses

200 Accepted

{
  "ok": true
}
Errors: 400, 401, 429
  • 400 The body is not a JSON object or a field is not valid (invalid_json, validation_failed)
  • 401 No Conversion tracking key, or an unknown or revoked one (publishable_key_required, invalid_key)
  • 429 Too many conversions from this client or for this key (rate_limited)

Conversion tracking script

GET /t/onesend.js

Browser script (under 2 KB). Add <script src="https://<your server>/t/onesend.js" data-key="os_pub_…" async></script> to your pages, then call onesend.convert({ goal, value, currency, id }). convert() also accepts key to override data-key.

Authentication: None.

Responses

200 JavaScript (application/javascript)

Receive a provider webhook

POST /hooks/{provider}/{connectionId}/{token}

Delivery events from a sending provider. Use the webhookUrl returned by GET /v1/connections/{id}; its last segment is a secret token derived from ONESEND_SECRET. OneSend registers this URL with providers that support it. Without a valid token, the request is accepted only when the provider signature verifies (Resend, MailerSend, Mailgun with a signing key).

Authentication: None.

Parameters

NameInTypeDescription
providerrequiredpathstring
connectionIdrequiredpathstring
tokenrequiredpathstring

Request body

application/json, optional. The provider's own webhook payload.

any

Responses

200 Processed

{
  "ok": true,
  "received": number,
  "ignored": boolean
}
Errors: 400, 401, 404
  • 400 The body could not be parsed (unparseable)
  • 401 Unknown webhook URL or invalid provider signature (invalid_hook_token, invalid_signature)
  • 404 Unknown connection (connection_not_found)

Health check

GET /healthz

Returns 200 when the server can reach its database, 503 otherwise. Use it for load balancer and container health checks.

Authentication: None.

Responses

200 Healthy

{
  "ok": true,
  "version": string,
  "time": string
}
Errors: 503
  • 503 The database is not reachable