API / Lists¶

Method	Endpoint	Description
GET	/api/lists	Retrieve all lists.
GET	/api/public/lists	Retrieve public lists.
GET	/api/lists/{list_id}	Retrieve a specific list.
POST	/api/lists	Create a new list.
PUT	/api/lists/{list_id}	Update a list.
DELETE	/api/lists/{list_id}	Delete a list.

GET /api/lists¶

Retrieve lists.

Parameters¶

Name	Type	Description
query	string	string for list name search.
status	[]string	Status to filter lists. Repeat in the query for multiple values.
tag	[]string	Tags to filter lists. Repeat in the query for multiple values.
order_by	string	Sort field. Options: name, status, created_at, updated_at.
order	string	Sorting order. Options: ASC, DESC.
page	number	Page number for pagination.
per_page	number	Results per page. Set to 'all' to return all results.

Example Request¶

curl -u "api_user:token" -X GET 'http://localhost:9000/api/lists?page=1&per_page=100'

Example Response¶

{
    "data": {
        "results": [
            {
                "id": 1,
                "created_at": "2020-02-10T23:07:16.194843+01:00",
                "updated_at": "2020-03-06T22:32:01.118327+01:00",
                "uuid": "ce13e971-c2ed-4069-bd0c-240e9a9f56f9",
                "name": "Default list",
                "type": "public",
                "optin": "double",
                "tags": [
                    "test"
                ],
                "subscriber_count": 2
            },
            {
                "id": 2,
                "created_at": "2020-03-04T21:12:09.555013+01:00",
                "updated_at": "2020-03-06T22:34:46.405031+01:00",
                "uuid": "f20a2308-dfb5-4420-a56d-ecf0618a102d",
                "name": "get",
                "type": "private",
                "optin": "single",
                "tags": [],
                "subscriber_count": 0
            }
        ],
        "total": 5,
        "per_page": 20,
        "page": 1
    }
}

GET /api/public/lists¶

Retrieve public lists with name and uuid to submit a subscription. This is an unauthenticated call to enable scripting to subscription form.

Example Request¶

curl -X GET 'http://localhost:9000/api/public/lists'

Example Response¶

[
  {
    "uuid": "55e243af-80c6-4169-8d7f-bc571e0269e9",
    "name": "Opt-in list"
  }
]

GET /api/lists/{list_id}¶

Retrieve a specific list.

Parameters¶

Name	Type	Required	Description
list_id	number	Yes	ID of the list to retrieve.

Example Request¶

curl -u "api_user:token" -X GET 'http://localhost:9000/api/lists/5'

Example Response¶

{
    "data": {
        "id": 5,
        "created_at": "2020-03-07T06:31:06.072483+01:00",
        "updated_at": "2020-03-07T06:31:06.072483+01:00",
        "uuid": "1bb246ab-7417-4cef-bddc-8fc8fc941d3a",
        "name": "Test list",
        "type": "public",
        "optin": "double",
        "tags": [],
        "subscriber_count": 0
    }
}

POST /api/lists¶

Create a new list.

Parameters¶

Name	Type	Required	Description
name	string	Yes	Name of the new list.
type	string	Yes	Type of list. Options: private, public.
optin	string	Yes	Opt-in type. Options: single, double.
tags	string[]		Associated tags for a list.
description	string	No	Description of the new list.

Example Request¶

curl -u "api_user:token" -X POST 'http://localhost:9000/api/lists'

Example Response¶

{
    "data": {
        "id": 5,
        "created_at": "2020-03-07T06:31:06.072483+01:00",
        "updated_at": "2020-03-07T06:31:06.072483+01:00",
        "uuid": "1bb246ab-7417-4cef-bddc-8fc8fc941d3a",
        "name": "Test list",
        "type": "public",
        "tags": [],
        "subscriber_count": 0,
        "description": "This is a test list"
    }
}
null

PUT /api/lists/{list_id}¶

Update a list.

Parameters¶

Name	Type	Required	Description
list_id	number	Yes	ID of the list to update.
name	string		New name for the list.
type	string		Type of list. Options: private, public.
optin	string		Opt-in type. Options: single, double.
tags	string[]		Associated tags for the list.
description	string		Description of the new list.

Example Request¶

curl -u "api_user:token" -X PUT 'http://localhost:9000/api/lists/5' \
--form 'name=modified test list' \
--form 'type=private'

Example Response¶

{
    "data": {
        "id": 5,
        "created_at": "2020-03-07T06:31:06.072483+01:00",
        "updated_at": "2020-03-07T06:52:15.208075+01:00",
        "uuid": "1bb246ab-7417-4cef-bddc-8fc8fc941d3a",
        "name": "modified test list",
        "type": "private",
        "optin": "single",
        "tags": [],
        "subscriber_count": 0,
        "description": "This is a test list"
    }
}

DELETE /api/lists/{list_id}¶

Delete a specific list.

Parameters¶

Name	Type	Required	Description
list_id	Number	Yes	ID of the list to delete.

Example Request¶

curl -u 'api_username:access_token' -X DELETE 'http://localhost:9000/api/lists/1'

Example Response¶

{
    "data": true
}