Docs / API reference

Contacts

Contacts and their attributes. Emails are unique per workspace (stored lowercased).

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

List contact attributes

GET /v1/contact-attributes

System attributes (email, first_name, last_name, phone) are always present.

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

Responses

200 Success

{
  "data": [{
    "key": string,
    "label": string,
    "type": "text" | "number" | "date" | "boolean" | "category",
    "options": [string],
    "system": boolean
  }]
}
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 contact attribute

POST /v1/contact-attributes

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

Request body

application/json, required.

FieldTypeDescription
keyrequiredstring
labelrequiredstring
typerequired"text" | "number" | "date" | "boolean" | "category"
optionsarray of string

Responses

201 Success

{
  "key": string,
  "label": string,
  "type": "text" | "number" | "date" | "boolean" | "category",
  "options": [string],
  "system": boolean
}
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 contact attribute

DELETE /v1/contact-attributes/{key}

Values already stored on contacts are kept.

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

Parameters

NameInTypeDescription
keyrequiredpathstring

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)

List contacts

GET /v1/contacts

cursor is a row offset: pass back nextCursor unchanged. total is the number of matching contacts.

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

Parameters

NameInTypeDescription
cursorquerystring
limitqueryintegerDefault 50. 1 to 200.
qquerystring
listIdquerystring
segmentIdquerystring
statusquerystring
qualityquerystringComma separated address quality values (ok, invalid, typo, no_mx, disposable, role, unchecked).

Responses

200 Success

{
  "data": [{
    "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
  }],
  "nextCursor": string or null,
  "total": number
}
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 or update a contact (by email)

POST /v1/contacts

Attributes are merged; null removes one. listIds are added to existing memberships.

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

Request body

application/json, required.

FieldTypeDescription
emailrequiredstring (email)Unique per workspace; stored lowercased. Creating an existing email updates that contact.
firstNamestring or nullAvailable in templates as {{first_name}}.
lastNamestring or nullAvailable in templates as {{last_name}}.
phonestring or null
attributesobjectCustom attributes by key, for example { "plan": "pro" }. Available in templates as {{plan}} or {{contact.plan}}. Keys you have not created under contact attributes are stored, but not exported or offered in the segment builder.
listIdsarray of stringLists to add the contact to.
status"subscribed" | "unsubscribed" | "bounced" | "complained" | "pending" | "inactive"Defaults to subscribed.

Responses

201 Success

{
  "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)

Bulk actions on contacts

POST /v1/contacts/bulk

Actions: add_to_list / remove_from_list (with listId or listIds), unsubscribe, resubscribe (only contacts that unsubscribed, never bounced or complained ones), delete.

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

Request body

application/json, required.

FieldTypeDescription
idsrequiredarray of stringAt most 10000 items.
actionrequired"add_to_lists" | "remove_from_lists" | "add_to_list" | "remove_from_list" | "unsubscribe" | "resubscribe" | "delete"
listIdsarray of string
listIdstring

Responses

200 Success

{
  "updated": number,
  "affected": number
}
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)

Export contacts as CSV (streamed)

GET /v1/contacts/export

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

Parameters

NameInTypeDescription
formatquery"csv"Default "csv".
listIdquerystring
segmentIdquerystring
statusquerystring
qquerystring

Responses

200 Success (text/csv)

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)

Get a contact

GET /v1/contacts/{id}

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

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "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, 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 contact

PATCH /v1/contacts/{id}

Attributes are merged (null removes one). listIds, when given, replaces the contact’s list memberships. Setting status: "subscribed" resubscribes an unsubscribed contact.

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

Parameters

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
emailstring (email)Unique per workspace; stored lowercased. Creating an existing email updates that contact.
firstNamestring or nullAvailable in templates as {{first_name}}.
lastNamestring or nullAvailable in templates as {{last_name}}.
phonestring or null
attributesobjectCustom attributes by key, for example { "plan": "pro" }. Available in templates as {{plan}} or {{contact.plan}}. Keys you have not created under contact attributes are stored, but not exported or offered in the segment builder.
listIdsarray of stringLists to add the contact to.
status"subscribed" | "unsubscribed" | "bounced" | "complained" | "pending" | "inactive"Defaults to subscribed.

Responses

200 Success

{
  "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)

Delete a contact

DELETE /v1/contacts/{id}

Removes the contact and its list memberships. Suppressions are kept, so a deleted address that bounced stays blocked. With erase=true (GDPR erasure), the address is also removed from messages, events, campaign recipients, clicks, conversions, form submissions and received mail, and a suppression keyed by a hash of the address keeps the person from being mailed again. See docs/privacy.md.

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

Parameters

NameInTypeDescription
idrequiredpathstring
erasequery"true" | "false"

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)

Contact activity timeline

GET /v1/contacts/{id}/activity

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

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "data": [{
    "type": "sent" | "delivered" | "opened" | "clicked" | "bounced" | "unsubscribed" | "complained" | "converted" | "added_to_list" | "imported",
    "campaignId": string or null,
    "campaignName": string or null,
    "messageId": string or null,
    "detail": string or null,
    "occurredAt": 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)

Automations a contact went through

GET /v1/contacts/{id}/journeys

Runs (newest first) with each step the contact passed, and the contact's recent tracked events.

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

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "data": [{
    "id": string,
    "object": "automation_run",
    "automationId": string,
    "automationName": string or null,
    "version": number,
    "contactId": string,
    "email": string or null,
    "status": "active" | "waiting" | "completed" | "exited" | "failed" | "canceled",
    "stepId": string or null,
    "waitingFor": "wait" | "event" | "quiet_hours" | "frequency_cap" | null,
    "nextRunAt": string or null,
    "exitReason": string or null,
    "lastError": string or null,
    "test": boolean,
    "emailsSent": number,
    "goalReachedAt": string or null,
    "enteredAt": string,
    "completedAt": string or null,
    "steps": [{ … }]
  }],
  "events": [{
    "id": string,
    "name": string,
    "properties": object,
    "occurredAt": 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)

Export a contact's data (GDPR)

GET /v1/contacts/{id}/export

Everything stored about one person in this workspace, as JSON: the contact, lists, suppression, campaign deliveries, messages, events, clicks, conversions, form submissions and mail received from the address. To erase the person, use DELETE /v1/contacts/{id}?erase=true.

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

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

object
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)