Get All Lists

GET https://emailoctopus.com/api/1.6/lists

Get details of all lists.

Parameters
api_key (string)	Your API key.
limit (integer)	The number of records to return per page, up to a maximum of 100. Defaults to 100.
page (integer)	A specific page to return records from. Defaults to 1.

200 (success) returns

data (array of structs)

Details of each list:

id (string) The identifier of the list.

name (string) The name of the list.

double_opt_in (boolean) If double opt-in has been enabled on the list.

fields (array)

tag (string)	The identifier used to reference the field in your emails.
type (string)	The type of the field - can be `NUMBER`, `TEXT` or `DATE`.
label (string)	A human readable label for the field.
fallback (string)	A default value for the field, used when there is no other value available.

counts (struct)

The summary counts of the list:

pending (integer)	The number of pending contacts in the list.
subscribed (integer)	The number of subscribed contacts in the list.
unsubscribed (integer)	The number of unsubscribed contacts in the list.

created_at (string) When the list was created, in ISO 8601 format.

paging (struct)

URLs to navigate the results:

previous (nullable string)	A link for the immediate previous page of results.
next (nullable string)	A link for the immediate next page of results.

Non-200 (error) returns

Details of the error:

code (string)	The error code.
message (string)	A description of the error.

Method-specific error codes
None.

API-wide error codes
INVALID_PARAMETERS	Parameters are missing or invalid.
API_KEY_INVALID	Your API key is invalid.
UNAUTHORISED	You're not authorised to perform that action.
NOT_FOUND	The requested endpoint does not exist.
UNKNOWN	An unknown error has occurred.

Example request
/api/1.6/lists?api_key=00000000-0000-0000-0000-000000000000

Example response

Example response
{ "data": [ { "id": "00000000-0000-0000-0000-000000000000", "name": "Foo", "double_opt_in": false, "fields": [ { "tag": "EmailAddress", "type": "TEXT", "label": "Email address", "fallback": null }, { "tag": "FirstName", "type": "TEXT", "label": "First name", "fallback": null }, { "tag": "LastName", "type": "TEXT", "label": "Last name", "fallback": null } ], "counts": { "pending": 0, "subscribed": 24, "unsubscribed": 1 }, "created_at": "2025-10-28T15:17:21+00:00" }, { "id": "00000000-0000-0000-0000-000000000001", "name": "Bar", "double_opt_in": true, "fields": [ { "tag": "EmailAddress", "type": "TEXT", "label": "Email address", "fallback": null }, { "tag": "FirstName", "type": "TEXT", "label": "First name", "fallback": null }, { "tag": "LastName", "type": "TEXT", "label": "Last name", "fallback": null } ], "counts": { "pending": 2, "subscribed": 14, "unsubscribed": 0 }, "created_at": "2025-10-29T15:17:21+00:00" } ], "paging": { "next": null, "previous": null } }

  { "data": [ { "id": "00000000-0000-0000-0000-000000000000", "name": "Foo", "double_opt_in": false, "fields": [ { "tag": "EmailAddress", "type": "TEXT", "label": "Email address", "fallback": null }, { "tag": "FirstName", "type": "TEXT", "label": "First name", "fallback": null }, { "tag": "LastName", "type": "TEXT", "label": "Last name", "fallback": null } ], "counts": { "pending": 0, "subscribed": 24, "unsubscribed": 1 }, "created_at": "2025-10-28T15:17:21+00:00" }, { "id": "00000000-0000-0000-0000-000000000001", "name": "Bar", "double_opt_in": true, "fields": [ { "tag": "EmailAddress", "type": "TEXT", "label": "Email address", "fallback": null }, { "tag": "FirstName", "type": "TEXT", "label": "First name", "fallback": null }, { "tag": "LastName", "type": "TEXT", "label": "Last name", "fallback": null } ], "counts": { "pending": 2, "subscribed": 14, "unsubscribed": 0 }, "created_at": "2025-10-29T15:17:21+00:00" } ], "paging": { "next": null, "previous": null } }

Code sample copy
curl -X GET \ https://emailoctopus.com/api/1.6/lists?api_key=00000000-0000-0000-0000-000000000000
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://emailoctopus.com/api/1.6/lists?api_key=00000000-0000-0000-0000-000000000000'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET'); $result = curl_exec($ch); if (curl_errno($ch)) { echo 'Error:' . curl_error($ch); } curl_close($ch);
import requests params = ( ('api_key', '00000000-0000-0000-0000-000000000000'), ) response = requests.get('https://emailoctopus.com/api/1.6/lists', params=params)
var https = require('https'); var options = { hostname: 'emailoctopus.com', port: 443, path: '/api/1.6/lists?api_key=00000000-0000-0000-0000-000000000000', method: 'GET', }; var req = https.request(options); req.end();
package main import ( "io/ioutil" "log" "net/http" ) func main() { client := &http.Client{} req, err := http.NewRequest("GET", "https://emailoctopus.com/api/1.6/lists?api_key=00000000-0000-0000-0000-000000000000", nil) if err != nil { log.Fatal(err) } resp, err := client.Do(req) if err != nil { log.Fatal(err) } bodyText, err := ioutil.ReadAll(resp.Body) if err != nil { log.Fatal(err) } }