usend Docs
API endpoints

Contacts

Manage account-wide contacts and their segment memberships.

Account-wide contacts represent each email address once across your organization. Changes apply to the address in every segment it belongs to. Every endpoint that takes {id_or_email} accepts a contact ID or an email address. See Contacts and segments.

The contact object

JSON
{
  "object": "contact",
  "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "email": "[email protected]",
  "first_name": "Ann",
  "last_name": "Lee",
  "unsubscribed": false,
  "created_at": "2026-10-11T08:10:00.000Z"
}

Create a contact

POST /contacts

NameTypeRequiredDescription
emailstringYesThe email address. Stored in lowercase.
first_namestringNoFirst name.
last_namestringNoLast name.
unsubscribedbooleanNoDefault false.
segmentsstring[]NoSegment IDs to add the contact to. Without it, the contact joins the default General segment. segment_id or audience_id (a single ID) are also accepted.
cURL
curl -X POST https://api.usend.et/contacts \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "Ann",
    "segments": ["78261eea-8f8b-4381-83c6-79fa7120f1cf"]
  }'
Response
{ "object": "contact", "id": "e169aa45-1ecf-4183-9955-b1499d5701d3" }

With a single segment, an address that is already in it fails with 409 conflict. With several segments, the segments that already contain the address are skipped.

Retrieve a contact

GET /contacts/{id_or_email}

cURL
curl https://api.usend.et/contacts/[email protected] \
  -H "Authorization: Bearer us_123456789"

Returns the contact object.

List contacts

GET /contacts

One row per email address. Paginated.

NameTypeRequiredDescription
segment_idstringNoOnly contacts in this segment. audience_id is also accepted.
limitintegerNo1 to 100. Default 50.
afterstringNoReturn contacts older than this ID.
beforestringNoReturn contacts newer than this ID.
cURL
curl "https://api.usend.et/contacts?segment_id=78261eea-8f8b-4381-83c6-79fa7120f1cf" \
  -H "Authorization: Bearer us_123456789"
Response
{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
      "email": "[email protected]",
      "first_name": "Ann",
      "last_name": "Lee",
      "unsubscribed": false,
      "created_at": "2026-10-11T08:10:00.000Z"
    }
  ],
  "has_more": false
}

Update a contact

PATCH /contacts/{id_or_email}

Updates the address in every segment it belongs to.

NameTypeRequiredDescription
first_namestringNoFirst name.
last_namestringNoLast name.
unsubscribedbooleanNoUnsubscribe or resubscribe the address everywhere.
cURL
curl -X PATCH https://api.usend.et/contacts/[email protected] \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Annie" }'

Returns the updated contact object.

Delete a contact

DELETE /contacts/{id_or_email}

Removes the address from every segment.

cURL
curl -X DELETE https://api.usend.et/contacts/[email protected] \
  -H "Authorization: Bearer us_123456789"
Response
{ "object": "contact", "id": "e169aa45-1ecf-4183-9955-b1499d5701d3", "deleted": true }

List a contact's segments

GET /contacts/{id_or_email}/segments

cURL
curl https://api.usend.et/contacts/[email protected]/segments \
  -H "Authorization: Bearer us_123456789"
Response
{
  "object": "list",
  "data": [
    {
      "object": "segment",
      "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
      "name": "Newsletter",
      "created_at": "2026-10-11T08:00:00.000Z",
      "contact_count": 1240
    }
  ],
  "has_more": false
}

Add a contact to a segment

POST /contacts/{id_or_email}/segments/{segment_id}

Copies the contact's details into the segment. Adding a contact that is already in the segment succeeds without changes.

cURL
curl -X POST https://api.usend.et/contacts/[email protected]/segments/78261eea-8f8b-4381-83c6-79fa7120f1cf \
  -H "Authorization: Bearer us_123456789"
Response
{ "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }

Remove a contact from a segment

DELETE /contacts/{id_or_email}/segments/{segment_id}

cURL
curl -X DELETE https://api.usend.et/contacts/[email protected]/segments/78261eea-8f8b-4381-83c6-79fa7120f1cf \
  -H "Authorization: Bearer us_123456789"
Response
{ "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf", "deleted": true }