Contacts

Manage your email contacts within lists.

GET/api/v1/contacts

List all contacts for the authenticated client. Cursor-paginated. Supports optional query parameters: lists[] (array of list IDs), tags[] (array of tag IDs), topics[] (array of topic IDs — matches contacts currently subscribed), search (partial match on name/email), include_unsubscribed (bool, default false), per_page (default 25, max 100), and cursor (next/previous page token).

Response Fields

idinteger

The contact ID.

uuidstring

The contact UUID.

namestring

The contact's full name.

emailstring

The contact's email address.

extra_attributesobject

Custom attributes stored on the contact.

unsubscribed_atstring|null

Timestamp when the contact unsubscribed, or null.

unsubscribed_by_contactboolean

Whether the contact unsubscribed themselves.

tagsarray

Tags assigned to the contact.

listsarray

Lists the contact belongs to.

topicsarray

Topics the contact is subscribed to.

created_atstring

ISO 8601 creation timestamp.

Request

curl -X GET \
  "https://byomailer.com/api/v1/contacts" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json"

Response

200

{
  "data": [
    {
      "id": 1,
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "John Doe",
      "email": "[email protected]",
      "extra_attributes": {
        "company": "Acme Inc"
      },
      "unsubscribed_at": null,
      "unsubscribed_by_contact": false,
      "tags": [
        {
          "id": 1,
          "uuid": "tag-uuid-1",
          "name": "newsletter",
          "created_at": "2024-01-15T10:30:00.000000Z"
        }
      ],
      "lists": [
        {
          "id": 1,
          "uuid": "list-uuid-1",
          "name": "Weekly Newsletter",
          "created_at": "2024-01-10T08:00:00.000000Z"
        }
      ],
      "topics": [
        {
          "id": 1,
          "uuid": "topic-uuid-1",
          "list_id": 1,
          "name": "Product Updates",
          "description": null,
          "created_at": "2024-01-15T10:30:00.000000Z"
        }
      ],
      "created_at": "2024-01-15T10:30:00.000000Z"
    }
  ],
  "meta": {
    "path": "https://byomailer.com/api/v1/contacts",
    "per_page": 25,
    "next_cursor": "eyJpZCI6MTAxLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
    "prev_cursor": null
  }
}

GET/api/v1/contacts/{contactId}

Retrieve a single contact by ID, including tags, lists, and topics.

Path Parameters

contactIdinteger

required

The ID of the contact to retrieve.

Response Fields

idinteger

The contact ID.

uuidstring

The contact UUID.

namestring

The contact's full name.

emailstring

The contact's email address.

extra_attributesobject

Custom attributes stored on the contact.

unsubscribed_atstring|null

Timestamp when the contact unsubscribed, or null.

unsubscribed_by_contactboolean

Whether the contact unsubscribed themselves.

tagsarray

Tags assigned to the contact.

listsarray

Lists the contact belongs to.

topicsarray

Topics the contact is subscribed to.

created_atstring

ISO 8601 creation timestamp.

Request

curl -X GET \
  "https://byomailer.com/api/v1/contacts/{contactId}" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json"

Response

200

{
  "data": {
    "id": 1,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "John Doe",
    "email": "[email protected]",
    "extra_attributes": {
      "company": "Acme Inc",
      "phone": "+1234567890"
    },
    "unsubscribed_at": null,
    "unsubscribed_by_contact": false,
    "tags": [
      {
        "id": 1,
        "uuid": "tag-uuid-1",
        "name": "newsletter",
        "created_at": "2024-01-15T10:30:00.000000Z"
      }
    ],
    "lists": [
      {
        "id": 1,
        "uuid": "list-uuid-1",
        "name": "Weekly Newsletter",
        "created_at": "2024-01-10T08:00:00.000000Z"
      }
    ],
    "topics": [
      {
        "id": 1,
        "uuid": "topic-uuid-1",
        "list_id": 1,
        "name": "Product Updates",
        "description": null,
        "created_at": "2024-01-15T10:30:00.000000Z"
      }
    ],
    "created_at": "2024-01-15T10:30:00.000000Z"
  }
}

POST/api/v1/lists/{listId}/contacts

Create a new contact or update an existing one and assign them to the specified list.

Path Parameters

listIdinteger

required

The ID of the list to add the contact to.

Body Parameters

emailstring

required

The email address of the contact.

namestring

The full name of the contact.

tagsstring[]

An array of tag names to assign to the contact. Tags are created automatically if they don't exist.

*string

Any additional fields are stored as extra attributes on the contact (e.g. company, phone).

Response Fields

idinteger

The contact ID.

uuidstring

The contact UUID.

namestring

The contact's full name.

emailstring

The contact's email address.

extra_attributesobject

Custom attributes stored on the contact.

unsubscribed_atstring|null

Timestamp when the contact unsubscribed, or null.

tagsarray

Tags assigned to the contact.

listsarray

Lists the contact belongs to.

created_atstring

ISO 8601 creation timestamp.

Request

curl -X POST \
  "https://byomailer.com/api/v1/lists/{listId}/contacts" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]",
  "name": "John Doe",
  "tags": [
    "newsletter",
    "customer"
  ],
  "company": "Acme Inc",
  "phone": "+1234567890"
}'

Response

201

{
  "data": {
    "id": 1,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "John Doe",
    "email": "[email protected]",
    "extra_attributes": {
      "company": "Acme Inc",
      "phone": "+1234567890"
    },
    "unsubscribed_at": null,
    "unsubscribed_by_contact": false,
    "tags": [
      {
        "id": 1,
        "uuid": "tag-uuid-1",
        "name": "newsletter",
        "created_at": "2024-01-15T10:30:00.000000Z"
      }
    ],
    "lists": [
      {
        "id": 1,
        "uuid": "list-uuid-1",
        "name": "Weekly Newsletter",
        "created_at": "2024-01-10T08:00:00.000000Z"
      }
    ],
    "created_at": "2024-01-15T10:30:00.000000Z"
  }
}

PUT/api/v1/contacts/{contactId}

Update an existing contact by ID.

Path Parameters

contactIdinteger

required

The ID of the contact to update.

Body Parameters

namestring

The full name of the contact.

tagsstring[]

An array of tag names. Replaces the contact's existing tags.

*string

Any additional fields are stored as extra attributes on the contact.

Response Fields

idinteger

The contact ID.

uuidstring

The contact UUID.

namestring

The updated contact name.

emailstring

The contact's email address.

extra_attributesobject

Custom attributes stored on the contact.

tagsarray

Updated tags assigned to the contact.

listsarray

Lists the contact belongs to.

created_atstring

ISO 8601 creation timestamp.

Request

curl -X PUT \
  "https://byomailer.com/api/v1/contacts/{contactId}" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "John Smith",
  "tags": [
    "vip",
    "customer"
  ]
}'

Response

200

{
  "data": {
    "id": 1,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "John Smith",
    "email": "[email protected]",
    "extra_attributes": {
      "company": "Acme Inc",
      "phone": "+1234567890"
    },
    "unsubscribed_at": null,
    "unsubscribed_by_contact": false,
    "tags": [
      {
        "id": 3,
        "uuid": "tag-uuid-3",
        "name": "vip",
        "created_at": "2024-01-15T10:30:00.000000Z"
      }
    ],
    "lists": [
      {
        "id": 1,
        "uuid": "list-uuid-1",
        "name": "Weekly Newsletter",
        "created_at": "2024-01-10T08:00:00.000000Z"
      }
    ],
    "created_at": "2024-01-15T10:30:00.000000Z"
  }
}

POST/api/v1/contacts/{contactId}/unsubscribe

Unsubscribe a contact. The contact is marked as unsubscribed and will no longer receive emails.

Path Parameters

contactIdinteger

required

The ID of the contact to unsubscribe.

Response Fields

idinteger

The contact ID.

uuidstring

The contact UUID.

namestring

The contact's full name.

emailstring

The contact's email address.

extra_attributesobject

Custom attributes stored on the contact.

unsubscribed_atstring

Timestamp when the contact was unsubscribed.

unsubscribed_by_contactboolean

Whether the contact unsubscribed themselves.

tagsarray

Tags assigned to the contact.

listsarray

Lists the contact belongs to.

created_atstring

ISO 8601 creation timestamp.

Request

curl -X POST \
  "https://byomailer.com/api/v1/contacts/{contactId}/unsubscribe" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json"

Response

200

{
  "data": {
    "id": 1,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "John Doe",
    "email": "[email protected]",
    "extra_attributes": {},
    "unsubscribed_at": "2024-01-16T14:00:00.000000Z",
    "unsubscribed_by_contact": false,
    "tags": [],
    "lists": [
      {
        "id": 1,
        "uuid": "list-uuid-1",
        "name": "Weekly Newsletter",
        "created_at": "2024-01-10T08:00:00.000000Z"
      }
    ],
    "created_at": "2024-01-15T10:30:00.000000Z"
  }
}

DELETE/api/v1/lists/{listId}/contacts/{contactId}

Remove a contact from a specific list. The contact is not deleted, only disassociated from the list.

Path Parameters

listIdinteger

required

The ID of the list to remove the contact from.

contactIdinteger

required

The ID of the contact to remove.

Response Fields

idinteger

The contact ID.

uuidstring

The contact UUID.

namestring

The contact's full name.

emailstring

The contact's email address.

tagsarray

Tags assigned to the contact (empty after removal).

listsarray

Remaining lists (empty if removed from all).

Request

curl -X DELETE \
  "https://byomailer.com/api/v1/lists/{listId}/contacts/{contactId}" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json"

Response

200

{
  "data": {
    "id": 1,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "John Doe",
    "email": "[email protected]",
    "extra_attributes": {},
    "unsubscribed_at": null,
    "unsubscribed_by_contact": false,
    "tags": [],
    "lists": [],
    "created_at": "2024-01-15T10:30:00.000000Z"
  }
}