Contact list management resource¶

The contact list resource handles creation, editing, deletion of contact lists and of individual contacts contained within.

Also see: Contact list resource PHP code samples

Get all contact lists¶

The resource results can be filtered using the optional querystring parameters:

filter - all
orderby - one of name, total, lastsenttolist
offset
limit

Request:

GET /contact/list?filter=all&orderby=email

Response

{
  "contacts": [
    {
      "list_id": 0,
      "name": "all",
      "lastsenttolist": null,
      "total": "2"
    },
    {
      "list_id": "1",
      "name": "test1",
      "lastsenttolist": "0000-00-00 00:00:00",
      "total": "13"
    }
  ]
  "total": 2,
  "filters": {
    "filter": "all",
    "orderby": "email",
    "offset": 0,
    "limit": 1000
  }
}

Get a single contact list with its recipients¶

The resource results can be filtered using the optional querystring parameters:

filter - one of all, subscribed, unsubscribed
orderby - one of email, added
offset
limit

Request:

GET /contact/list/{LIST_HASH}?filter=all&orderby=email

Response

{
  "contacts": [
    {
      "recipient_id": "13328313",
      "email": "test1@example.org",
      "added": "2012-10-11 18:03:41"
    },
    {
      "recipient_id": "13134105",
      "email": "test2@example.org",
      "added": "2012-09-05 12:06:13"
    },
  ],
  "name": "all",
  "total": "2",
  "stats": {
    "total": 2,
    "unsubscribed": 0,
    "subscribed": 2
  },
  "filters": {
    "filter": "all",
    "orderby": "email",
    "offset": 0,
    "limit": 1000
  }
}

Get a single contact list in CSV format¶

May change in the future to use the `Accept` header

The resource results can be filtered using the optional querystring parameters:

filter - one of all, subscribed, unsubscribed

Request:

GET /contact/csv/{LIST_HASH}

Response:

Content-type: text/csv
Content-disposition: attachment; filename=listname-filter.csv

email,firstname,lastname,added
email@example.org,John,Doe,2013-01-01 10:00:00
email2@example.org,Jane,Doe,2013-01-01 10:00:00

Get a single recipient from a contact list¶

Request:

GET /contact/list/{LIST_HASH}/rcpt/{EMAIL}

Response

{
  "contacts": [
      {
        "email": "email@example.org",
        "added": "2012-06-24 07:10:42"
      }
  ]
}

Add contacts with custom fields to contactlist¶

If you want to add contacts with custom fields, the contacts can be given as a map of key-value pairs:

Request

POST /contact/list/{LIST_HASH}

{
    "name": "Contact list name",
    "contacts": [
        {
            "email": "email@example.org",
            "firstname": "John",
            "lastname": "Doe"
        },
        {
            "email": "email2@example.org",
            "firstname": "Jane",
            "lastname": "Doe"
        }
    ]
}

Response

Status: 201

{
    "status": "created",
    "columns": "3",
    "id": "1"
}

A more compact format which we support is using a definition list. The input can be significantly smaller for large lists.

Request

POST /contact/list

{
    "name": "Contact list name",
    "definition": ["email", "name"],
    "contacts": [
        ["email@example.org", "John"],
        ["email2@example.org", "Jane"]
    ]
}

Response

Status: 201

{
    "status": "created",
    "columns": "2",
    "id": "1"
}

Edit an existing contact list¶

Add new contacts to an existing contact list. The contacts map supports the same format used for contact list creation, including custom fields. If the contact already exists, the custom fields will be overridden.

Possible action values are:

subscribe
resubscribe
unsubscribe

Request

POST /contact/list/{LIST_HASH}

{
    "contacts": ["email@example.org", "email2@example.org"],
    "action": "subscribe"
}

Response

{"status": "saved"}

Manage a single recipient from a contact list¶

Edit a contact’s subscription. Possible status values are:

subscribe
unsubscribe

Request

POST /contact/list/{LIST_HASH}/rcpt/{EMAIL}

{
    "status": "unsubscribe"
}

Response

{
    "status": "modified"
}