Docs / API reference

Segments

Saved conditions over attributes, list membership, engagement and status.

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

List segments (with contact counts)

GET /v1/segments

counts=false skips counting and returns the last computed contactCount (with countedAt) — use it for pickers. counts=live recounts every segment. By default counts are reused until contacts, lists or engagement change.

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

Parameters

NameInTypeDescription
countsquery"true" | "false" | "none" | "live"

Responses

200 Success

{
  "data": [{
    "id": string,
    "object": "segment",
    "name": string,
    "match": "all" | "any",
    "conditions": [object],
    "contactCount": number,
    "countedAt": string or null,
    "createdAt": string
  }],
  "nextCursor": string or null
}
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)

Create a segment

POST /v1/segments

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

Request body

application/json, required.

FieldTypeDescription
namerequiredstring
match"all" | "any"Default "all".
conditionsrequiredarray of object

Responses

201 Success

{
  "id": string,
  "object": "segment",
  "name": string,
  "match": "all" | "any",
  "conditions": [object],
  "contactCount": number,
  "countedAt": string or null,
  "createdAt": string
}
Errors: 400, 401, 403, 404, 409, 413, 415, 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)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Count contacts matching unsaved conditions

POST /v1/segments/preview

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

Request body

application/json, required.

FieldTypeDescription
match"all" | "any"Default "all".
conditionsrequiredarray of object

Responses

200 Success

{
  "count": number,
  "sample": [{
    "id": string,
    "object": "contact",
    "email": string,
    "firstName": string or null,
    "lastName": string or null,
    "phone": string or null,
    "attributes": object,
    "listIds": [string],
    "status": "subscribed" | "unsubscribed" | "bounced" | "complained" | "pending" | "inactive",
    "source": "import" | "api" | "form" | "manual" | null,
    "engagement": {
      "lastOpenedAt": string or null,
      "lastClickedAt": string or null,
      "campaignsReceived": number,
      "opens": number,
      "clicks": number
    },
    "quality": "ok" | "invalid" | "typo" | "no_mx" | "disposable" | "role" | null,
    "qualitySuggestion": string or null,
    "sunsetState": "reengage_sent" | "inactive" | null,
    "consent": {
      "method": "double_opt_in" | "single_opt_in" | "import" | "api",
      "formId": string or null,
      "submissionId": string or null,
      "importId": string or null,
      "submittedAt": string or null,
      "confirmedAt": string or null,
      "ipHash": string or null,
      "userAgent": string or null,
      "consentText": string or null,
      "consentVersion": number or null,
      "confirmedElsewhere": boolean
    },
    "createdAt": string,
    "updatedAt": string
  }]
}
Errors: 400, 401, 403, 404, 409, 413, 415, 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)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Get a segment

GET /v1/segments/{id}

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

Parameters

NameInTypeDescription
idrequiredpathstring
countsquery"true" | "false" | "none" | "live"

Responses

200 Success

{
  "id": string,
  "object": "segment",
  "name": string,
  "match": "all" | "any",
  "conditions": [object],
  "contactCount": number,
  "countedAt": string or null,
  "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)

Update a segment

PATCH /v1/segments/{id}

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

Parameters

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
namestring
match"all" | "any"Default "all".
conditionsarray of object

Responses

200 Success

{
  "id": string,
  "object": "segment",
  "name": string,
  "match": "all" | "any",
  "conditions": [object],
  "contactCount": number,
  "countedAt": string or null,
  "createdAt": string
}
Errors: 400, 401, 403, 404, 409, 413, 415, 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)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Delete a segment

DELETE /v1/segments/{id}

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

Parameters

NameInTypeDescription
idrequiredpathstring

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)