Lists

Manage mailing lists.

GET/api/v1/lists

Get all mailing lists for the authenticated client. Cursor-paginated (per_page default 25, max 100; cursor for next/previous page).

Response Fields

idinteger

The list ID.

uuidstring

The list UUID.

namestring

The list name.

created_atstring

ISO 8601 creation timestamp.

metaobject

Cursor pagination metadata (path, per_page, next_cursor, prev_cursor).

Request

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

Response

200

{
  "data": [
    {
      "id": 1,
      "uuid": "list-uuid-1",
      "name": "Weekly Newsletter",
      "created_at": "2024-01-10T08:00:00.000000Z"
    },
    {
      "id": 2,
      "uuid": "list-uuid-2",
      "name": "Product Updates",
      "created_at": "2024-01-12T15:30:00.000000Z"
    }
  ],
  "meta": {
    "path": "https://byomailer.com/api/v1/lists",
    "per_page": 25,
    "next_cursor": null,
    "prev_cursor": null
  }
}

POST/api/v1/lists

Create a new mailing list.

Body Parameters

namestring

required

The name of the mailing list.

Response Fields

idinteger

The list ID.

uuidstring

The list UUID.

namestring

The list name.

created_atstring

ISO 8601 creation timestamp.

Request

curl -X POST \
  "https://byomailer.com/api/v1/lists" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Beta Testers"
}'

Response

201

{
  "data": {
    "id": 3,
    "uuid": "list-uuid-3",
    "name": "Beta Testers",
    "created_at": "2024-01-16T12:00:00.000000Z"
  }
}

PATCH/api/v1/lists/{listId}

Update an existing mailing list.

Path Parameters

listIdinteger

required

The ID of the list to update.

Body Parameters

namestring

required

The new name for the mailing list.

Response Fields

idinteger

The list ID.

uuidstring

The list UUID.

namestring

The updated list name.

created_atstring

ISO 8601 creation timestamp.

Request

curl -X PATCH \
  "https://byomailer.com/api/v1/lists/{listId}" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Early Access Users"
}'

Response

200

{
  "data": {
    "id": 3,
    "uuid": "list-uuid-3",
    "name": "Early Access Users",
    "created_at": "2024-01-16T12:00:00.000000Z"
  }
}

DELETE/api/v1/lists/{listId}

Delete a mailing list.

Path Parameters

listIdinteger

required

The ID of the list to delete.

Request

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

Response

204

No content