Contacts and segments

Contacts are the people you send broadcasts to. Each contact has an email address, an optional first and last name, and an unsubscribed flag. Contacts are grouped into audiences, also called segments.

#Audiences and segments

An audience and a segment are the same thing under two names, available at /audiences and /segments. They share the same IDs, so you can create one through either endpoint and use it with the other. A broadcast is sent to one audience or segment.

curl -X POST https://api.usend.et/segments \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Newsletter" }'

{ "object": "segment", "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf", "name": "Newsletter" }

A segment that a broadcast uses cannot be deleted. Delete the broadcast first.

#Two ways to manage contacts

#Account-wide contacts

/contacts treats each email address as one contact across your organization, with its segment memberships. Use it when the same person can be in several segments.

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",
    "last_name": "Lee",
    "segments": ["78261eea-8f8b-4381-83c6-79fa7120f1cf"]
  }'

• Without segments, the contact joins a default segment named General, created when first needed.
• GET /contacts lists one row per address. Filter by segment with ?segment_id=.
• GET, PATCH and DELETE /contacts/{id_or_email} accept a contact ID or an email address, and act on the address in every segment it belongs to. Updating unsubscribed on an account-wide contact unsubscribes it everywhere.
• Manage memberships with GET /contacts/{id_or_email}/segments, POST /contacts/{id_or_email}/segments/{segment_id} and DELETE /contacts/{id_or_email}/segments/{segment_id}.

#Contacts in an audience

/audiences/{audience_id}/contacts manages the contacts of one audience.

curl -X POST https://api.usend.et/audiences/78261eea-8f8b-4381-83c6-79fa7120f1cf/contacts \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "first_name": "Ann" }'

Here, a contact's changes apply to that audience only.

Email addresses are stored in lowercase. An address can be in an audience only once: adding it again fails with 409 conflict.

#Import contacts from CSV

Import many contacts into an audience at once with POST /audiences/{audience_id}/contacts/import, or from the Audiences page in the dashboard. Send the CSV text in the csv field:

curl -X POST https://api.usend.et/audiences/78261eea-8f8b-4381-83c6-79fa7120f1cf/contacts/import \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "csv": "email,first_name,last_name\[email protected],Ann,Lee\[email protected],Ben,Okafor" }'

{ "imported": 2, "skipped": 0 }

• If the first row is a header, columns are matched by name: email (or email_address, e-mail), first_name (or firstname, first) and last_name (or lastname, last). Other columns are ignored.
• Without a header, columns are read as email, first name, last name.
• Rows with an invalid address, or an address already in the audience, are skipped and counted in skipped.

#Unsubscribes

Contacts with unsubscribed: true never receive broadcasts. A contact becomes unsubscribed when:

• They click the unsubscribe link in a broadcast, or use their mail client's unsubscribe button. This also fires a contact.unsubscribed webhook event.
• You set unsubscribed: true through the API or the dashboard.

Unsubscribing applies to the audience the broadcast was sent to.

See the API reference for audiences, contacts and segments.