Contacts
Contacts and their attributes. Emails are unique per workspace (stored lowercased).
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
{
"data": [{
"key": string,
"label": string,
"type": "text" | "number" | "date" | "boolean" | "category",
"options": [string],
"system": boolean
}]
}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)
Create a contact attribute
POST /v1/contact-attributes
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
keyrequired | string | |
labelrequired | string | |
typerequired | "text" | "number" | "date" | "boolean" | "category" | |
options | array of string |
Responses
{
"key": string,
"label": string,
"type": "text" | "number" | "date" | "boolean" | "category",
"options": [string],
"system": boolean
}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)
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
| Name | In | Type | Description |
|---|---|---|---|
keyrequired | path | string |
Responses
Errors: 400, 401, 403, 404, 409, 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)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| Name | In | Type | Description |
|---|---|---|---|
cursor | query | string | |
limit | query | integer | Default 50. 1 to 200. |
q | query | string | |
listId | query | string | |
segmentId | query | string | |
status | query | string | |
quality | query | string | Comma separated address quality values (ok, invalid, typo, no_mx, disposable, role, unchecked). |
Responses
{
"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
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)
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
| Field | Type | Description |
|---|---|---|
emailrequired | string (email) | Unique per workspace; stored lowercased. Creating an existing email updates that contact. |
firstName | string or null | Available in templates as {{first_name}}. |
lastName | string or null | Available in templates as {{last_name}}. |
phone | string or null | |
attributes | object | Custom 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. |
listIds | array of string | Lists to add the contact to. |
status | "subscribed" | "unsubscribed" | "bounced" | "complained" | "pending" | "inactive" | Defaults to subscribed. |
Responses
{
"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
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)
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
| Field | Type | Description |
|---|---|---|
idsrequired | array of string | At most 10000 items. |
actionrequired | "add_to_lists" | "remove_from_lists" | "add_to_list" | "remove_from_list" | "unsubscribe" | "resubscribe" | "delete" | |
listIds | array of string | |
listId | string |
Responses
{
"updated": number,
"affected": number
}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)
Export contacts as CSV (streamed)
GET /v1/contacts/export
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
format | query | "csv" | Default "csv". |
listId | query | string | |
segmentId | query | string | |
status | query | string | |
q | query | string |
Responses
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)
Get a contact
GET /v1/contacts/{id}
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
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)
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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
email | string (email) | Unique per workspace; stored lowercased. Creating an existing email updates that contact. |
firstName | string or null | Available in templates as {{first_name}}. |
lastName | string or null | Available in templates as {{last_name}}. |
phone | string or null | |
attributes | object | Custom 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. |
listIds | array of string | Lists to add the contact to. |
status | "subscribed" | "unsubscribed" | "bounced" | "complained" | "pending" | "inactive" | Defaults to subscribed. |
Responses
{
"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
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)
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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
erase | query | "true" | "false" |
Responses
Errors: 400, 401, 403, 404, 409, 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)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Contact activity timeline
GET /v1/contacts/{id}/activity
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
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)
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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
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)
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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
objectErrors: 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)