EmailOctopus logo

API > Lists > Get List

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

Get details of a list.

Parameters
api_key (string) Your API key.
200 (success) returns

Details of the 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.
Non-200 (error) returns

Details of the error:

code (string) The error code.
message (string) A description of the error.
Method-specific error codes
LIST_NOT_FOUND The list could not be found.
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/00000000-0000-0000-0000-000000000000?api_key=00000000-0000-0000-0000-000000000000
Example response 
                        
                            {
                                "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
                                    }
                                ],
                                "tags": [
                                    "vip",
                                    "buyer"
                                ],
                                "counts": {
                                    "pending": 0,
                                    "subscribed": 5,
                                    "unsubscribed": 0
                                },
                                "created_at": "2025-06-30T00:00:00+00:00"
                            }
Code sample
copy