Public endpoints
Endpoints outside /v1: browser conversions, provider webhooks, inbound ingest and health. Most do not use an API key.
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
| Field | Type | Description |
|---|---|---|
token | string | The os_ct click token from the landing URL. onesend.token() returns it. |
goal | string | |
value | number | |
currency | string | |
idempotencyKey | string | For example the order id. Repeated keys are recorded once. |
Responses
{
"ok": true
}Errors: 400, 401, 429
400The body is not a JSON object or a field is not valid (invalid_json,validation_failed)401No Conversion tracking key, or an unknown or revoked one (publishable_key_required,invalid_key)429Too 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
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
| Name | In | Type | Description |
|---|---|---|---|
providerrequired | path | string | |
connectionIdrequired | path | string | |
tokenrequired | path | string |
Request body
anyResponses
{
"ok": true,
"received": number,
"ignored": boolean
}Errors: 400, 401, 404
400The body could not be parsed (unparseable)401Unknown webhook URL or invalid provider signature (invalid_hook_token,invalid_signature)404Unknown 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
{
"ok": true,
"version": string,
"time": string
}Errors: 503
503The database is not reachable