---
title: "Public endpoints API"
description: "Public endpoints in the OneSend API: 4 endpoints. Endpoints outside /v1: browser conversions, provider webhooks, inbound ingest and health. Most do not use an API key."
url: https://onesend.email/docs/api-reference/public-endpoints/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/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](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## 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.

| 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

`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

| Name | In | Type | Description |
|---|---|---|---|
| `provider`required | path | `string` |  |
| `connectionId`required | path | `string` |  |
| `token`required | path | `string` |  |

### 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
