Contacts

Retrieve a list of contacts

GET /contacts

Query parameters

Name	Type	Required	Description
`limit`	`integer`	no	Number of items to return.
`after`	`string`	no	Return items after this cursor.
`before`	`string`	no	Return items before this cursor.

Example

curl -X GET "$SESAMESEND_URL/contacts" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
      "email": "ada@example.com",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "created_at": "2023-10-06 23:47:56.678+00",
      "unsubscribed": false
    }
  ]
}

Create a new contact

POST /contacts

Body

Field	Type	Required	Description
`email`	`string`	yes	Email address of the contact.
`first_name`	`string`	no	First name of the contact.
`last_name`	`string`	no	Last name of the contact.
`unsubscribed`	`boolean`	no	The Contact's global subscription status. If set to true, the contact will be unsubscribed from all Broadcasts.
`properties`	`object`	no	A map of custom property keys and values to create.
`segments`	`object[]`	no	Array of segment IDs to add the contact to.
`segments[].id`	`string`	no	The segment ID
`topics`	`object[]`	no	Array of topic subscriptions for the contact.
`topics[].id`	`string`	no	The topic ID.
`topics[].subscription`	`"opt_in" \| "opt_out"`	no	The subscription status for this topic.
`audience_id`	`string`	no	Unique identifier of the audience to which the contact belongs.

Example

curl -X POST "$SESAMESEND_URL/contacts" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "unsubscribed": false,
  "audience_id": "78261eea-8f8b-4381-83c6-79fa7120f1cf"
}'

Responses

Status	Description
`201`	OK

{
  "object": "contact",
  "id": "479e3145-dd38-476b-932c-529ceb705947"
}

Retrieve a list of contact imports

GET /contacts/imports

Query parameters

Name	Type	Required	Description
`status`	`"queued" \| "in_progress" \| "completed" \| "failed"`	no	Filter contact imports by status.
`limit`	`integer`	no	Number of items to return.
`after`	`string`	no	Return items after this cursor.
`before`	`string`	no	Return items before this cursor.

Example

curl -X GET "$SESAMESEND_URL/contacts/imports" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact_import",
      "id": "479e3145-dd38-476b-932c-529ceb705947",
      "status": "completed",
      "created_at": "2023-10-06 23:47:56.678+00",
      "completed_at": "2023-10-06 23:50:56.678+00",
      "counts": {
        "total": 100,
        "created": 80,
        "updated": 10,
        "skipped": 5,
        "failed": 5
      }
    }
  ]
}

Create a contact import

POST /contacts/imports

Example

curl -X POST "$SESAMESEND_URL/contacts/imports" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`201`	OK

{
  "object": "contact_import",
  "id": "479e3145-dd38-476b-932c-529ceb705947"
}

Retrieve a single contact import

GET /contacts/imports/{id}

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	The Contact Import ID.

Example

curl -X GET "$SESAMESEND_URL/contacts/imports/<id>" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "object": "contact_import",
  "id": "479e3145-dd38-476b-932c-529ceb705947",
  "status": "completed",
  "created_at": "2023-10-06 23:47:56.678+00",
  "completed_at": "2023-10-06 23:50:56.678+00",
  "counts": {
    "total": 100,
    "created": 80,
    "updated": 10,
    "skipped": 5,
    "failed": 5
  }
}

Retrieve a single contact by ID or email

GET /contacts/{id}

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	The Contact ID or email address.

Example

curl -X GET "$SESAMESEND_URL/contacts/<id>" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "object": "contact",
  "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "created_at": "2023-10-06 23:47:56.678+00",
  "unsubscribed": false,
  "properties": {}
}

Update a single contact by ID or email

PATCH /contacts/{id}

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	The Contact ID or email address.

Body

Field	Type	Required	Description
`email`	`string`	no	Email address of the contact.
`first_name`	`string`	no	First name of the contact.
`last_name`	`string`	no	Last name of the contact.
`unsubscribed`	`boolean`	no	The Contact's global subscription status. If set to true, the contact will be unsubscribed from all Broadcasts.
`properties`	`object`	no	A map of custom property keys and values to update.

Example

curl -X PATCH "$SESAMESEND_URL/contacts/<id>" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "unsubscribed": false
}'

Responses

Status	Description
`200`	OK

{
  "object": "contact",
  "id": "479e3145-dd38-476b-932c-529ceb705947"
}

Remove an existing contact by ID or email

DELETE /contacts/{id}

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	The Contact ID or email address.

Example

curl -X DELETE "$SESAMESEND_URL/contacts/<id>" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "object": "contact",
  "id": "520784e2-887d-4c25-b53c-4ad46ad38100",
  "deleted": true
}

Retrieve a list of segments for a contact

GET /contacts/{contact_id}/segments

Path parameters

Name	Type	Required	Description
`contact_id`	`string`	yes	The Contact ID or email address.

Query parameters

Name	Type	Required	Description
`limit`	`integer`	no	Number of items to return.
`after`	`string`	no	Return items after this cursor.
`before`	`string`	no	Return items before this cursor.

Example

curl -X GET "$SESAMESEND_URL/contacts/<contact_id>/segments" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "string",
      "name": "string",
      "created_at": "2023-10-06 23:47:56.678+00"
    }
  ]
}

Add a contact to a segment

POST /contacts/{contact_id}/segments/{segment_id}

Path parameters

Name	Type	Required	Description
`contact_id`	`string`	yes	The Contact ID or email address.
`segment_id`	`string`	yes	The Segment ID.

Example

curl -X POST "$SESAMESEND_URL/contacts/<contact_id>/segments/<segment_id>" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "object": "contact_segment",
  "contact_id": "string",
  "segment_id": "string"
}

Remove a contact from a segment

DELETE /contacts/{contact_id}/segments/{segment_id}

Path parameters

Name	Type	Required	Description
`contact_id`	`string`	yes	The Contact ID or email address.
`segment_id`	`string`	yes	The Segment ID.

Example

curl -X DELETE "$SESAMESEND_URL/contacts/<contact_id>/segments/<segment_id>" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "object": "contact_segment",
  "contact_id": "string",
  "segment_id": "string",
  "deleted": true
}

Retrieve topics for a contact

GET /contacts/{contact_id}/topics

Path parameters

Name	Type	Required	Description
`contact_id`	`string`	yes	The Contact ID or email address.

Query parameters

Name	Type	Required	Description
`limit`	`integer`	no	Number of items to return.
`after`	`string`	no	Return items after this cursor.
`before`	`string`	no	Return items before this cursor.

Example

curl -X GET "$SESAMESEND_URL/contacts/<contact_id>/topics" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Responses

Status	Description
`200`	OK

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "subscription": "opt_in"
    }
  ]
}

Update topics for a contact

PATCH /contacts/{contact_id}/topics

Path parameters

Name	Type	Required	Description
`contact_id`	`string`	yes	The Contact ID or email address.

Body

Field	Type	Required	Description
`topics`	`object[]`	yes
`topics[].id`	`string`	no	The ID of the topic.
`topics[].subscription`	`"opt_in" \| "opt_out"`	no	The subscription status (opt_in or opt_out).

Example

curl -X PATCH "$SESAMESEND_URL/contacts/<contact_id>/topics" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "topics": [
    {}
  ]
}'

Responses

Status	Description
`200`	OK

{
  "object": "contact_topics",
  "contact_id": "string",
  "topics": [
    {
      "id": "string",
      "subscription": "opt_in"
    }
  ]
}

Retrieve a list of contactsCopy Anchor Link

Create a new contactCopy Anchor Link

Retrieve a list of contact importsCopy Anchor Link

Create a contact importCopy Anchor Link

Retrieve a single contact importCopy Anchor Link

Retrieve a single contact by ID or emailCopy Anchor Link

Update a single contact by ID or emailCopy Anchor Link

Remove an existing contact by ID or emailCopy Anchor Link

Retrieve a list of segments for a contactCopy Anchor Link

Add a contact to a segmentCopy Anchor Link

Remove a contact from a segmentCopy Anchor Link

Retrieve topics for a contactCopy Anchor Link

Update topics for a contactCopy Anchor Link

On this page

Retrieve a list of contacts

Create a new contact

Retrieve a list of contact imports

Create a contact import

Retrieve a single contact import

Retrieve a single contact by ID or email

Update a single contact by ID or email

Remove an existing contact by ID or email

Retrieve a list of segments for a contact

Add a contact to a segment

Remove a contact from a segment

Retrieve topics for a contact

Update topics for a contact