Subscribers¶

GET /api/v1/lists/(int: list_id)/subscribers¶

Subscribers of the list matching the specified list_id.

Query Parameters:
Parameters:	list_id (int) – list’s unique identifier
	subscription – filter results by `subscription` status, valid values are `active`, `pending`, `bounced`, `unsubscribed` and `deleted` email – filter results by `email`
Response JSON Array of Objects:
	id (int) – subscriber’s unique identifier create_datetime (datetime) – subscriber’s creation datetime create_user (int) – subscriber’s creation user‘s unique identifier update_datetime (datetime) – subscriber’s last update datetime update_user (int) – subscriber’s last update user‘s unique identifier subscription (string) – subscriber’s subscription status email (email) – subscriber’s email first_name (string) – subscriber’s first name last_name (string) – subscriber’s last name gender (string) – subscriber’s gender date_of_birth (date) – subscriber’s date of birth language (string) – subscriber’s language region (string) – subscriber’s region

Note

Custom shared and list fields should also be part of the subscriber objects. The exact structure of the list can be retrieved by introspecting the resource.

Request:

GET /api/v1/lists/1/subscribers HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Response:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

{
    "count": 3,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "create_datetime": "2014-01-09T13:51:50.549536Z",
            "create_user": 1,
            "update_datetime": "2015-10-08T12:32:59.330455Z",
            "update_user": 1,
            "subscription": "active",
            "email": "active@example.com",
            "first_name": "Sergio",
            "last_name": "Leone",
            "gender": "m",
            "date_of_birth": "1929-01-03",
            "language": "it",
            "region": "IT-RM"
        },
        {
            "id": 2,
            "create_datetime": "2014-01-09T13:51:50.549536Z",
            "create_user": 1,
            "update_datetime": "2015-10-08T12:32:59.330455Z",
            "update_user": 1,
            "subscription": "bounced",
            "email": "bounced@example.com",
            "first_name": "Ennio",
            "last_name": "Morricone",
            "gender": "m",
            "date_of_birth": "1928-11-10",
            "language": "it",
            "region": "IT-RM"
        },
        {
            "id": 3,
            "create_datetime": "2014-01-09T13:51:50.549536Z",
            "create_user": 1,
            "update_datetime": "2015-10-08T12:32:59.330455Z",
            "update_user": 1,
            "subscription": "deleted",
            "email": "deleted@example.com",
            "first_name": "Clint",
            "last_name": "Eastwood",
            "gender": "m",
            "date_of_birth": "1930-05-31",
            "language": "en",
            "region": "US-CA"
        }
    ]
}

Status Codes:	404 Not Found – no subscriber list match the specified `list_id`

POST /api/v1/lists/(int: list_id)/subscribers¶

Create subscriber for the list matching the specified list_id.

Request JSON Object:
Parameters:	list_id (int) – list’s unique identifier
	email (email) – subscriber’s email first_name (string) – subscriber’s first name last_name (string) – subscriber’s last name gender (string) – subscriber’s gender date_of_birth (date) – subscriber’s date of birth language (string) – subscriber’s language region (string) – subscriber’s region

Note

Custom shared and list fields can also be specified as parameters. The exact structure of the list can be retrieved by introspecting the resource.

Response JSON Object:

id (int) – subscriber’s unique identifier
create_datetime (datetime) – subscriber’s creation datetime
create_user (int) – subscriber’s creation user‘s unique identifier
update_datetime (datetime) – subscriber’s last update datetime
update_user (int) – subscriber’s last update user‘s unique identifier
subscription (string) – subscriber’s subscription status
email (email) – subscriber’s email
first_name (string) – subscriber’s first name
last_name (string) – subscriber’s last name
gender (string) – subscriber’s gender
date_of_birth (date) – subscriber’s date of birth
language (string) – subscriber’s language
region (string) – subscriber’s region

Request:

POST /api/v1/lists/1/subscribers HTTP/1.1
Host: account.emailicious.com
Accept: application/json
Content-Type: application/json

{
    "email": "test@example.com",
    "first_name": "Dolly",
    "last_name": "Parton",
    "gender": "f",
    "date_of_birth": "1946-01-19",
    "language": "en",
    "region": "US-TN"
}

Response:

HTTP/1.1 201 CREATED
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

{
    "id": 1,
    "create_datetime": "2015-11-27T22:14:36.590658Z",
    "create_user": 1,
    "update_datetime": "2015-11-27T22:14:36.590711Z",
    "update_user": 1,
    "subscription": "active",
    "email": "test@example.com",
    "first_name": "Dolly",
    "last_name": "Parton",
    "gender": "f",
    "date_of_birth": "1946-01-19",
    "language": "en",
    "region": "US-TN"
}

Status Codes:	201 Created – the subscriber was created successfully 400 Bad Request – invalid subscriber data 404 Not Found – no subscriber list match the specified `list_id` 409 Conflict – a subscriber with the specified `email` already exists in this list.

Dealing with 409 Conflict

When a list already contains a subscriber with the specified email the conflicting subscriber will be returned in the body of a 409 Conflict response.

HTTP/1.1 409 CONFLICT
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

{
    "id": 2,
    "create_datetime": "2015-11-27T22:14:36.590658Z",
    "create_user": 1,
    "update_datetime": "2015-11-27T22:14:36.590711Z",
    "update_user": 1,
    "subscription": "active",
    "email": "conflict@example.com",
    "first_name": "Dolly",
    "last_name": "Parton",
    "gender": "f",
    "date_of_birth": "1946-01-19",
    "language": "en",
    "region": "US-TN"
}

At this point your application should either notify the user behind the request that this email is already subscribed or proceed to update the conflicting subscriber given you authenticated the user as the owner of the specified email address.

Note that that a conflict may occur even if the subscriber previously unsubscribed or was deleted from the specified list. You might want to take different action based on the returned subscription status and your application’s business logic such as confirming the re-activation.

OPTIONS /api/v1/lists/(int: list_id)/subscribers¶

Introspection details of the subscribers resource.

Parameters:	list_id (int) – list’s unique identifier

Request:

OPTIONS /api/v1/lists/1/subscribers HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Response:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

{
    "name": "Subscriber List",
    "renders": [
        "application/json",
        "text/html"
    ],
    "parses": [
        "application/json",
        "application/x-www-form-urlencoded",
        "multipart/form-data"
    ],
    "actions": {
        "POST": {
            "id": {
                "type": "integer",
                "required": false,
                "read_only": true,
                "label": "ID"
            },
            "create_datetime": {
                "type": "datetime",
                "required": false,
                "read_only": true,
                "label": "Create datetime"
            },
            "create_user": {
                "type": "field",
                "required": false,
                "read_only": true,
                "label": "Create user"
            },
            "update_datetime": {
                "type": "datetime",
                "required": false,
                "read_only": true,
                "label": "Update datetime"
            },
            "update_user": {
                "type": "field",
                "required": false,
                "read_only": true,
                "label": "Update user"
            },
            "subscription": {
                "type": "field",
                "required": false,
                "read_only": true,
                "label": "Subscription"
            },
            "email": {
                "type": "email",
                "required": true,
                "read_only": false,
                "label": "Email",
                "max_length": 254
            },
            "first_name": {
                "type": "string",
                "required": false,
                "read_only": false,
                "label": "First name",
                "max_length": 100
            },
            "last_name": {
                "type": "string",
                "required": false,
                "read_only": false,
                "label": "Last name",
                "max_length": 100
            },
            "gender": {
                "type": "choice",
                "required": false,
                "read_only": false,
                "label": "Gender",
                "choices": [
                    {
                        "display_name": "Unknown",
                        "value": ""
                    },
                    {
                        "display_name": "Male",
                        "value": "m"
                    },
                    {
                        "display_name": "Female",
                        "value": "f"
                    }
                ]
            },
            "date_of_birth": {
                "type": "date",
                "required": false,
                "read_only": false,
                "label": "Date of birth"
            },
            "language": {
                "type": "field",
                "required": false,
                "read_only": false,
                "label": "Language",
                "help_text": "ISO-639-1 language code."
            },
            "region": {
                "type": "field",
                "required": false,
                "read_only": false,
                "label": "Region",
                "help_text": "ISO-3166-1 country or ISO-3166-2 region code."
            }
        }
    }
}

Custom fields introspection

You can use the actions.POST details to retrieve the name and type of custom fields from the specified list_id structure.

Status Codes:	404 Not Found – no subscriber list match the specified `list_id`

GET /api/v1/lists/(int: list_id)/subscribers/(int: id)¶

Details of the subscriber matching the specified list_id and id.

Parameters:

list_id (int) – list’s unique identifier
id (int) – subscriber’s unique identifier

Response JSON Object:

id (int) – subscriber’s unique identifier
create_datetime (datetime) – subscriber’s creation datetime
create_user (int) – subscriber’s creation user‘s unique identifier
update_datetime (datetime) – subscriber’s last update datetime
update_user (int) – subscriber’s last update user‘s unique identifier
subscription (string) – subscriber’s subscription status
email (email) – subscriber’s email
first_name (string) – subscriber’s first name
last_name (string) – subscriber’s last name
gender (string) – subscriber’s gender
date_of_birth (date) – subscriber’s date of birth
language (string) – subscriber’s language
region (string) – subscriber’s region

Note

Custom shared and list fields should also be part of the subscriber object. The exact structure of the list can be retrieved by introspecting the resource.

Request:

GET /api/v1/lists/1/subscribers/1 HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Response:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

{
    "id": 1,
    "create_datetime": "2015-11-27T22:14:36.590658Z",
    "create_user": 1,
    "update_datetime": "2015-11-28T22:14:36.590711Z",
    "update_user": 1,
    "subscription": "active",
    "email": "test@example.com",
    "first_name": "Dolly",
    "last_name": "Parton",
    "gender": "f",
    "date_of_birth": "1946-01-19",
    "language": "en",
    "region": "US-TN"
}

Status Codes:	404 Not Found – no subscriber match the specified `list_id` and `id`

PUT /api/v1/lists/(int: list_id)/subscribers/(int: id)¶

Alter the subscriber matching the specified id and list_id.

Request JSON Object:
Parameters:	list_id (int) – list’s unique identifier id (int) – subscriber’s unique identifier
	email (email) – subscriber’s email first_name (string) – subscriber’s first name last_name (string) – subscriber’s last name gender (string) – subscriber’s gender date_of_birth (date) – subscriber’s date of birth language (string) – subscriber’s language region (string) – subscriber’s region

Note

Custom shared and list fields can also be specified as parameters. The exact structure of the list can be retrieved by introspecting the resource.

Response JSON Object:

id (int) – subscriber’s unique identifier
create_datetime (datetime) – subscriber’s creation datetime
create_user (int) – subscriber’s creation user‘s unique identifier
update_datetime (datetime) – subscriber’s last update datetime
update_user (int) – subscriber’s last update user‘s unique identifier
subscription (string) – subscriber’s subscription status
email (email) – subscriber’s email
first_name (string) – subscriber’s first name
last_name (string) – subscriber’s last name
gender (string) – subscriber’s gender
date_of_birth (date) – subscriber’s date of birth
language (string) – subscriber’s language
region (string) – subscriber’s region

Request:

POST /api/v1/lists/1/subscribers/1 HTTP/1.1
Host: account.emailicious.com
Accept: application/json
Content-Type: application/json

{
    "email": "test@example.com",
    "first_name": "Altered Dolly",
    "last_name": "Parton",
    "gender": "f",
    "date_of_birth": "1946-01-19",
    "language": "en",
    "region": "US-TN"
}

Response:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

{
    "id": 1,
    "create_datetime": "2015-11-27T22:14:36.590658Z",
    "create_user": 1,
    "update_datetime": "2015-11-28T22:14:36.590711Z",
    "update_user": 1,
    "subscription": "active",
    "email": "test@example.com",
    "first_name": "Altered Dolly",
    "last_name": "Parton",
    "gender": "f",
    "date_of_birth": "1946-01-19",
    "language": "en",
    "region": "US-TN"
}

Status Codes:	400 Bad Request – invalid subscriber data 404 Not Found – no subscriber match the specified `list_id` and `id` 409 Conflict – a subscriber with the specified `email` already exists in this list.

PATCH /api/v1/lists/(int: list_id)/subscribers/(int: id)¶

Partially alter the subscriber matching the specified id and list_id.

Request JSON Object:
Parameters:	list_id (int) – list’s unique identifier id (int) – subscriber’s unique identifier
	email (email) – subscriber’s email first_name (string) – subscriber’s first name last_name (string) – subscriber’s last name gender (string) – subscriber’s gender date_of_birth (date) – subscriber’s date of birth language (string) – subscriber’s language region (string) – subscriber’s region

Note

Custom shared and list fields can also be specified as parameters. The exact structure of the list can be retrieved by introspecting the resource.

Response JSON Object:

id (int) – subscriber’s unique identifier
create_datetime (datetime) – subscriber’s creation datetime
create_user (int) – subscriber’s creation user‘s unique identifier
update_datetime (datetime) – subscriber’s last update datetime
update_user (int) – subscriber’s last update user‘s unique identifier
subscription (string) – subscriber’s subscription status
email (email) – subscriber’s email
first_name (string) – subscriber’s first name
last_name (string) – subscriber’s last name
gender (string) – subscriber’s gender
date_of_birth (date) – subscriber’s date of birth
language (string) – subscriber’s language
region (string) – subscriber’s region

Request:

PATH /api/v1/lists/1/subscribers/1 HTTP/1.1
Host: account.emailicious.com
Accept: application/json
Content-Type: application/json

{
    "first_name": "Altered Dolly",
}

Response:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

{
    "id": 1,
    "create_datetime": "2015-11-27T22:14:36.590658Z",
    "create_user": 1,
    "update_datetime": "2015-11-28T22:14:36.590711Z",
    "update_user": 1,
    "subscription": "active",
    "email": "test@example.com",
    "first_name": "Altered Dolly",
    "last_name": "Parton",
    "gender": "f",
    "date_of_birth": "1946-01-19",
    "language": "en",
    "region": "US-TN"
}

Status Codes:	400 Bad Request – invalid subscriber data 404 Not Found – no subscriber match the specified `list_id` and `id` 409 Conflict – a subscriber with the specified `email` already exists in this list.

DELETE /api/v1/lists/(int: list_id)/subscribers/(int: id)¶

Change the subscription status of the subscriber matching the provided id and list_id to deleted.

Parameters:	list_id (int) – list’s unique identifier id (int) – subscriber’s unique identifier

Request:

DELETE /api/v1/lists/1/subscribers/1 HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Response:

HTTP/1.1 204 NO CONTENT
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH

Status Codes:	204 No Content – the subscriber was deleted successfully 404 Not Found – no subscriber match the specified `list_id` and `id`

POST /api/v1/lists/(int: list_id)/subscribers/(int: id)/activate¶

Change the subscription status of the subscriber matching the provided id and list_id to either pending or active depending on the list’s subscription process and the value of the confirm parameter.

Request JSON Object:
Parameters:	list_id (int) – list’s unique identifier id (int) – subscriber’s unique identifier
	confirm (boolean) – whether or not to force or disable activation confirmation
Response JSON Object:
	status (string) – the subscriber’s subscription status

POST /api/v1/lists/1/subscribers/1/activate HTTP/1.1
Host: account.emailicious.com
Accept: application/json

HTTP/1.1 200 OK
Vary: Accept
Allow: POST, OPTIONS
Content-Type: application/json

{
    "status": "active"
}

Status Codes:	400 Bad Request – the subscription activation cannot be confirmed since not opt-in process is configured for the specified list. 404 Not Found – no subscriber match the specified `list_id` and `id`

POST /api/v1/lists/(int: list_id)/subscribers/(int: id)/unsubscribe¶

Change the subscription status of the subscriber matching the provided id and list_id to unsubscribed.

Response JSON Object:
Parameters:	list_id (int) – list’s unique identifier id (int) – subscriber’s unique identifier
	status (string) – the subscriber’s subscription status

POST /api/v1/lists/1/subscribers/1/unsubscribe HTTP/1.1
Host: account.emailicious.com
Accept: application/json

HTTP/1.1 200 OK
Vary: Accept
Allow: POST, OPTIONS
Content-Type: application/json

{
    "status": "unsubscribed"
}

Status Codes:	404 Not Found – no subscriber match the specified `list_id` and `id`