RestApi.apib

FORMAT: 1A
HOST: https://example.com/api/v2

# phpList REST API v2


# Group Authentication

Resources related to login and logout.


## Session [/sessions]

### Create a new session (log in) [POST]

Given valid login data, this will generate a login token that will be
valid for 1 hour. It takes a JSON object containing the following key-value
pairs:

+ `login_name` (string): the login name of the superuser administrator to log in
+ `password` (string): the plain text password

Non-superuser administrators cannot authenticate via the REST API.

The login token then can be passed as basic auth password for requests
that require authentication. (The basic auth user name can be any string.)

+ Request (application/json)

    {
        "login_name": "admin",
        "password": "eetIc/Gropvoc1"
    }

+ Response 201 (application/json)

    + Body

        {
            "id": 1234,
            "key": "2cfe100561473c6cdd99c9e2f26fa974",
            "expiry": "2017-07-20T18:22:48+00:00"
        }

+ Response 400 (application/json)

    + Body

        {
            "code": 400,
            "message": "Empty JSON data"
        }

+ Response 400 (application/json)

    + Body

        {
            "code": 400,
            "message": 'Invalid json message received'
        }

+ Response 400 (application/json)

    + Body

        {
            "code": 400,
            "message": "Incomplete credentials"
        }

+ Response 401 (application/json)

    + Body

        {
            "code": 401,
            "message": "Not authorized"
        }

## Single session [/sessions/{session}]

### Destroy a the session (log out) [DELETE]

+ Request (application/json)

+ Response 204 (application/json)

+ Response 403 (application/json)

    + Body

        {
            "code": 403,
            "message": "No valid session key was provided as basic auth password."
        }

+ Response 403 (application/json)

    + Body

        {
            "code": 403,
            "message": "You do not have access to this session."
        }

+ Response 404 (application/json)

    + Body

        {
            "code": 404,
            "message": "There is no session with that ID."
        }


# Group Lists

Resources related to subscriber lists.

All requests in this group need to be authenticated with a valid session key
provided as basic auth password. (The basic auth user name can be any string.)


## Subscriber lists [/lists]

### Retrieve all subscriber lists [GET]

+ Request (application/json)

+ Response 200 (application/json)

    + Body

        {
            "name": "News",
            "description": "News (and some fun stuff)",
            "creation_date": "2016-06-22T15:01:17+00:00",
            "list_position": 12,
            "subject_prefix": "phpList",
            "public": true,
            "category": "news",
            "id": 1
        },
        {
            "name": "More news",
            "description": "",
            "creation_date": "2016-06-22T15:01:17+00:00",
            "list_position": 12,
            "subject_prefix": "",
            "public": true,
            "category": "",
            "id": 2
        }

+ Response 403 (application/json)

    + Body

        {
            "code": 403,
            "message": "No valid session key was provided as basic auth password."
        }

## Single subscriber list [/lists/{list}]

### Get the list data [GET]

+ Request (application/json)

+ Response 200 (application/json)

    + Body

        {
            "name": "News",
            "description": "News (and some fun stuff)",
            "creation_date": "2016-06-22T15:01:17+00:00",
            "list_position": 12,
            "subject_prefix": "phpList",
            "public": true,
            "category": "news",
            "id": 1
        }

+ Response 403 (application/json)

    + Body

        {
            "code": 403,
            "message": "No valid session key was provided as basic auth password."
        }

+ Response 404 (application/json)

    + Body

        {
            "code": 404,
            "message": "There is no list with that ID."
        }

### Delete a the list [DELETE]

+ Request (application/json)

+ Response 204 (application/json)

+ Response 403 (application/json)

    + Body

        {
            "code": 403,
            "message": "No valid session key was provided as basic auth password."
        }

+ Response 404 (application/json)

    + Body

        {
            "code": 404,
            "message": "There is no list with that ID."
        }

## Members of a subscriber list [/lists/{list}/members]

### Retrieve all members of a subscriber list [GET]

+ Request (application/json)

+ Response 200 (application/json)

    + Body

        {
            "creation_date" => "2016-07-22T15:01:17+00:00",
            "email" => "oliver@example.com",
            "confirmed" => true,
            "blacklisted" => true,
            "bounce_count" => 17,
            "unique_id" => "95feb7fe7e06e6c11ca8d0c48cb46e89",
            "html_email" => true,
            "disabled" => true,
            "id" => 1,
        },
        {
            "creation_date" => "2017-07-22T15:12:17+00:00",
            "email" => "sam@example.com",
            "confirmed" => true,
            "blacklisted" => false,
            "bounce_count" => 1,
            "unique_id" => "95feb7fe7e06e6c11ca8d0c48cb4616d",
            "html_email" => false,
            "disabled" => false,
            "id" => 2,
        }

+ Response 403 (application/json)

    + Body

        {
            "code": 403,
            "message": "No valid session key was provided as basic auth password."
        }

+ Response 404 (application/json)

    + Body

        {
            "code": 404,
            "message": "There is no list with that ID."
        }


## Members of a subscriber list [/lists/{list}/members]

### Retrieve all members of a subscriber list [GET]

+ Request (application/json)

+ Response 200 (application/json)

    + Body

        {
            "creation_date" => "2016-07-22T15:01:17+00:00",
            "email" => "oliver@example.com",
            "confirmed" => true,
            "blacklisted" => true,
            "bounce_count" => 17,
            "unique_id" => "95feb7fe7e06e6c11ca8d0c48cb46e89",
            "html_email" => true,
            "disabled" => true,
            "id" => 1,
        },
        {
            "creation_date" => "2017-07-22T15:12:17+00:00",
            "email" => "sam@example.com",
            "confirmed" => true,
            "blacklisted" => false,
            "bounce_count" => 1,
            "unique_id" => "95feb7fe7e06e6c11ca8d0c48cb4616d",
            "html_email" => false,
            "disabled" => false,
            "id" => 2,
        }

+ Response 403 (application/json)

    + Body

        {
            "code": 403,
            "message": "No valid session key was provided as basic auth password."
        }

+ Response 404 (application/json)

    + Body

        {
            "code": 404,
            "message": "There is no list with that ID."
        }


# Group Subscribers

Resources related to subscribers.

All requests in this group need to be authenticated with a valid session key
provided as basic auth password. (The basic auth user name can be any string.)

## Subscribers [/subscribers]

### Create a new subscriber [POST]

Given a valid authentication, this will generate a subscriber. It takes a JSON
object containing the following key-value pairs:

+ `email` (string): the email address of the subscriber (required)
+ `confirmed` (boolean): whether the subscriber already is confirmed (optional)
+ `blacklisted` (boolean): whether the subscriber is blacklisted (optional)
+ `html_email` (boolean): whether the subscriber would like to receive emails
  in HTML format (optional)
+ `disabled` (boolean): whether the subscriber is disabled (optional)

+ Response 201 (application/json)

    + Body

        {
            "creation_date": "2017-12-16T18:44:27+00:00",
            "email": "subscriber@example.com",
            "confirmed": false,
            "blacklisted": false,
            "bounce_count": 0,
            "unique_id": "69f4e92cf50eafca9627f35704f030f4",
            "html_email": true,
            "disabled": false,
            "id": 1
        }

+ Response 403 (application/json)

    + Body

        {
            "code": 403,
            "message": "No valid session key was provided as basic auth password."
        }

+ Response 409 (application/json)

    + Body

        {
            "code": 409,
            "message": "This resource already exists."
        }

+ Response 422 (application/json)

    + Body

        {
            "code": 422,
            "message": "Some fields invalid: email, confirmed, html_email"
        }