Conversions
Credit purchases, sign-ups and other goals to the email that drove them.
List conversions
GET /v1/conversions
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
cursor | query | string | |
limit | query | integer | Default 50. 1 to 200. |
campaignId | query | string |
Responses
{
"data": [{
"id": string,
"goal": string,
"value": number or null,
"currency": string or null,
"contactId": string or null,
"email": string or null,
"campaignId": string or null,
"messageId": string or null,
"attributedBy": "token" | "message" | "email" | "none",
"occurredAt": string
}],
"nextCursor": string or null
}Errors: 400, 401, 403, 404, 429, 500
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Record a conversion
POST /v1/conversions
Attribution: token (the os_ct query parameter added to tracked links) → messageId → email (the most recent campaign click by that address within the attribution window, 7 days by default). Send idempotencyKey (e.g. your order id) to make retries safe.
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
token | string | The os_ct query parameter added to tracked links. Best attribution. |
messageId | string | Credit a specific email. |
email | string (email) | Credit the most recent campaign click by this address within the attribution window. |
campaignId | string | With email: only consider this campaign. |
goal | string | What happened, for example purchase or signup. Default "conversion". |
value | number | Revenue, at most 1,000,000,000. 0 to 1000000000. |
currency | string | ISO currency, for example USD. |
occurredAt | string | When it happened (ISO 8601). Defaults to now. |
idempotencyKey | string | For example your order id: a retry with the same key is not counted twice. |
Responses
{
"id": string,
"goal": string,
"value": number or null,
"currency": string or null,
"contactId": string or null,
"email": string or null,
"campaignId": string or null,
"messageId": string or null,
"attributedBy": "token" | "message" | "email" | "none",
"occurredAt": string
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)