Knowledge Base
Page Menu      

    Lists

    Lists are sets of contacts a campaign can be sent to. A list consists of name, from name, reply-to fields and physical address that will be displayed in newsletter. Lists can be created, read, updated, deleted and filled up with contacts.

    NOTE: each list has properties, including physical address. Such address is merged into footers of newsletters when campaigns are sent to a list. It allows to send to different lists of contacts and display different physical addresses at the bottom of newsletters depending which list such email was sent to. This is a useful feature for agencies who manage email marketing campaigns on behalf of their clients.

    Get All Lists

    GET https://api.expresspigeon.com/lists

    Returns an array of all lists

    Example Request

    1
2

    curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/lists'
    1
2
3
4
5
6
7

    import org.javalite.http.Http;
import static org.javalite.common.JsonHelper.toList;

String response = Http.get("https://api.expresspigeon.com/lists")
        .header("X-auth-key", AUTH_KEY)
        .text();
List result = toList(response);
    1
2
3
4
5
6
7
8
9

    $options = array(
  'http' => array(
    'method' => 'GET',
    'header' => "X-auth-key: 00000000-0000-0000-0000-000000000000\r\n"
    )
);
$context = stream_context_create($options);
$result = file_get_contents('https://api.expresspigeon.com/lists', false, $context);
$response = json_decode($result);
    1
2
3
4
5

    require 'expresspigeon-ruby'
lists =  ExpressPigeon::API.lists.all
lists.each do |list|
   puts list["name"]
end
    1
2
3
4

    from expresspigeon import ExpressPigeon
    
api = ExpressPigeon()
response = api.lists.find_all()

    Example Response

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

    [{
    "id":1,
    "from_name":"Dave",
    "reply_to":"dave@example.com",
    "contact_count":12345,
    "zip":"60606",
    "state":"IL",
    "address1":"123 Pine St",
    "address2":"unit 128",
    "city":"Chicago",
    "country":"USA",
    "organization":"Acme Tools",
    "name":"Customers 2013",
    "created_at":"2013-01-21T12:27:36.000+0000"
},
{
    "id":2,
    "from_name":"Dave",
    "reply_to":"dave@example.com",
    "contact_count":2345,
    "zip":"60606",
    "state":"IL",
    "address1":"123 Pine St",
    "address2":"",
    "city":"Chicago",
    "country":"USA",
    "organization":"Acme Tools",
    "name":"Main list",
    "created_at":"2013-01-21T12:27:36.000+0000"
}]

    Create a New List

    POST https://api.expresspigeon.com/lists

    Creates a new list from given parameters. The request body must be a JSON object representing a list to be created. Please, do not forget to set content-type to application/json

    Request Parameters

    Parameter Required Description
    name Yes Name of a newly created list
    from_name Yes Default "from" name used when sending campaigns to this list
    reply_to Yes Default reply To email address used when sending campaigns to this list

    Example Request

    1
2
3
4
5
6

    curl -X POST -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
    -H "Content-type: application/json"      \
    -d '{ "name": "Active customers",        \
          "from_name": "Bob",                \
          "reply_to": "bob@acmetools.com" }'
    'https://api.expresspigeon.com/lists'
    1
2
3
4
5
6
7
8
9

    import org.javalite.http.Http;
import static org.javalite.common.Collections.map;
import static org.javalite.common.JsonHelper.toJsonString;
import static org.javalite.common.JsonHelper.toMap;

String content = toJsonString(map("name", "Active customers", "from_name", "Bob", "reply_to", "bob@acmetools.com"));
String response = Http.post("https://api.expresspigeon.com/lists", content)
               .header("X-auth-key", AUTH_KEY).header("Content-type", "application/json").text();
Map<String, Object> result = toMap(response);
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

    $data = array(
  'name' => 'Active customers',
  'from_name' => 'Bob',
  'reply_to' => 'bob@acmetools.com'
);
$options = array(
  'http' => array(
    'method' => 'POST',
    'content' => json_encode($data),
    'header' => "Content-Type: application/json\r\n" .
                "X-auth-key: 00000000-0000-0000-0000-000000000000\r\n"
    )
);
$context = stream_context_create($options);
$result = file_get_contents('https://api.expresspigeon.com/lists', false, $context);
$response = json_decode($result);
    1
2

    require 'expresspigeon-ruby'
list =  ExpressPigeon::API.lists.create 'Active customers', 'Bob', 'bob@acmetools.com'
    1
2
3
4

    from expresspigeon import ExpressPigeon
    
api = ExpressPigeon()
response = api.lists.create(name="Active customers", from_name="Bob", reply_to="bob@acmetools.com")

    Example Response

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

    {
    "status": "success",
    "code": 200,
    "message": "list=2 created/updated successfully",
    "list": {
        "id": 2,
        "name": "Active customers",
        "from_name": "Bob",
        "reply_to": "bob@acmetools.com",
        "contact_count": 0,
        "zip": "60089",
        "state": "IL",
        "address1": "123 Pine St.",
        "address2": "Unit 128",
        "city": "Chicago",
        "country": "USA",
        "organization": "Acme Tools",
        "created_at": "2013-01-21T12:27:36.000+0000"
    }        
}

    NOTE: The physical address defaulted to the physical address from the account.

    Update Existing List

    PUT https://api.expresspigeon.com/lists

    JSON object represents a list to be updated. The id field is required. This object can partially represent your list. Whatever fields you provide in the incoming document, will be updated. Omitted fields will stay unchanged.

    Request parameters

    Parameter Required Description
    id Yes The id of a list to be updated
    name No New "Name" field of the list
    from_name No New "From Name" field in the list
    reply_to No New "Reply To" field in the list
    organization No New "Organization" field in the list's physical address
    address1 No New "Address 1 line" field in the list's physical address
    address2 No New "Address 2 line" field in the list's physical address
    city No New "City" field in the list's physical address
    state No New "State" field in the list's physical address
    zip No New "Zip" field in the list's physical address
    country No New "Country" field in the list's physical address

    Example Request

    1
2
3
4
5
6
7
8
9

    curl -X PUT -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
    -H "Content-type: application/json" \
    -d '{
        "id": 2,
        "name": "Customers list",
        "from_name": "Bill",
        "reply_to": "bill@expresspigeon.com"
    }' \
'https://api.expresspigeon.com/lists'
    1
2
3
4
5
6
7
8
9
10
11
12
13
14

    import org.javalite.http.Http;
import static org.javalite.common.Collections.map;
import static org.javalite.common.JsonHelper.toJsonString;
import static org.javalite.common.JsonHelper.toMap;

String content = toJsonString(map("id", 2,
        "name", "Customers list",
        "from_name", "Bill",
        "reply_to", "bob@expresspigeon.com"));
String response = Http.put("https://api.expresspigeon.com/lists", content)
        .header("X-auth-key", AUTH_KEY)
        .header("Content-type", "application/json")
        .text();
Map<String, Object> result = toMap(response);
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

    $data = array(
  'id' => 2,
  'name' => 'Customers list',
  'from_name' => 'Bill',
  'reply_to' => 'bob@expresspigeon.com'
);
$options = array(
  'http' => array(
    'method' => 'PUT',
    'content' => json_encode($data),
    'header' => "Content-Type: application/json\r\n" .
                "X-auth-key: 00000000-0000-0000-0000-000000000000\r\n"
    )
);
$context = stream_context_create($options);
$result = file_get_contents('https://api.expresspigeon.com/lists', false, $context);
$response = json_decode($result);
    1
2
3
4

    require 'expresspigeon-ruby'

res = ExpressPigeon::API.lists.update list_id, :name => 'Real customers',
                                             :from_name => 'John', :reply_to => 'john@example.com'
    1
2
3
4

    from expresspigeon import ExpressPigeon
    
api = ExpressPigeon()
response = api.lists.update(2, {"name": "Customers list", "from_name": "Bill", "reply_to": "bob@expresspigeon.com"})

    Example Response

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

    {
    "status": "success",
    "code": 200,
    "message": "list=1 created/updated successfully",
    "list": {
        "id": 2,
        "name": "Customers list",
        "from_name": "Bill",
        "reply_to": "bill@expresspigeon.com",
        "contact_count": 0,
        "zip": "60089",
        "state": "IL",
        "address1": "113 N. McHenry",
        "address2": "#128",
        "city": "Buffalo Grove",
        "country": "USA",
        "organization": "ExpressPigeon",
        "created_at": "2013-01-21T12:27:36.000+0000"
    }
}

    Delete a List

    DELETE https://api.expresspigeon.com/lists/{id}

    Removes a list with a given id. A list must be enabled and has no dependent subscriptions and/or scheduled campaigns.

    Request parameters

    Parameter Required Description
    id Yes The id of a list to be removed

    Example Request

    1
2

    curl -X DELETE -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/lists/1'
    1
2
3
4
5
6
7

    import org.javalite.http.Http;
import static org.javalite.common.JsonHelper.toMap;

String response = Http.delete("https://api.expresspigeon.com/lists/2")
        .header("X-auth-key", AUTH_KEY)
        .text();
Map<String, Object> result = toMap(response);
    1
2
3
4
5
6
7
8
9

    $options = array(
  'http' => array(
    'method' => 'DELETE',
    'header' => "X-auth-key: 00000000-0000-0000-0000-000000000000\r\n"
    )
);
$context = stream_context_create($options);
$result = file_get_contents('https://api.expresspigeon.com/lists/2', false, $context);
$response = json_decode($result);
    1
2
3

    require 'expresspigeon-ruby'

res = ExpressPigeon::API.lists.delete(list_id)
    1
2
3
4

    from expresspigeon import ExpressPigeon
    
api = ExpressPigeon()
response = api.lists.delete(2)

    Example Response

    1
2
3
4
5

    {
    "status": "success",
    "code": 200,
    "message": "list=1 deleted successfully" 
}

    Download Contacts from List

    GET https://api.expresspigeon.com/lists/{list_id}/csv

    Removes a list with a given id. A list must be enabled and has no dependent subscriptions and/or scheduled campaigns.

    Request parameters

    Parameter Required Description
    list_id Yes A list id to select contacts from or "suppress_list" to select suppressed contacts

    Example Request

    1
2

    curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/lists/123/csv'
    1
2
3
4

    import org.javalite.http.Http;

String response = Http.get("https://api.expresspigeon.com/lists/123/csv")
                                .header("X-auth-key", AUTH_KEY).text();
    1
2
3

    $options = array('http' => array( 'method' => 'GET', 'header' => "X-auth-key: 00000000-0000-0000-0000-000000000000\r\n" ));
$context = stream_context_create($options);
$result = file_get_contents('https://api.expresspigeon.com/lists/123/csv', false, $context);
    1
2
3

    require 'lib/expresspigeon-ruby'

res = ExpressPigeon::API.lists.csv(list_id)
    1
2
3
4

    from expresspigeon import ExpressPigeon
    
api = ExpressPigeon()
response = api.lists.csv(123)

    Example Response

    1
2

    "Email", "First name", "Last name", "City", "Phone", "Company", "Title", "Address 1", "Address 2", "State", "Zip", "Country", "Date of birth", "Created"
"bob@example.net","Bob",,,,,,,,,,,"2018-04-09 14:15:57"

    Upload Contacts into List

    POST https://api.expresspigeon.com/lists/{id}/upload

    Creates or merges contacts from uploaded CSV or zipped CSV file.

    The request must use multipart/form-data with CSV or zipped CSV payload and contacts_file parameter pointed to CSV or zipped CSV file name.

    Example Request

    1
2
3

    curl -F "contacts_file=@list.csv;type=text/plain" \
    -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/lists/{list_id}/upload'
    1
2
3
4
5
6

    import org.javalite.http.Http;
import static org.javalite.common.JsonHelper.toMap;

String response = Http.multipart("https://api.expresspigeon.com/lists/" + listId + "upload")
        .header("X-auth-key", AUTH_KEY).file("contacts_file", "/path/to/list.csv").text();
Map<String, Object> result = toMap(response);
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

    $file_content = file_get_contents('/path/to/list.csv');

$eol = "\r\n";
$data = '';
 
$mime_boundary=md5(time());
 
$data .= '--' . $mime_boundary . $eol;
$data .= 'Content-Disposition: form-data; name="contacts_file"; filename="list.csv"' . $eol;
$data .= 'Content-Type: text/plain' . $eol;
$data .= 'Content-Transfer-Encoding: base64' . $eol . $eol;
$data .= $file_content . $eol;
$data .= "--" . $mime_boundary . "--" . $eol . $eol;
 
$params = array('http' => array(
                  'method' => 'POST',
                  'header' => 'X-auth-key: 00000000-0000-0000-0000-000000000000' . $eol .
                              'Content-Type: multipart/form-data; boundary=' . $mime_boundary . $eol,
                  'content' => $data
               ));
 
$ctx = stream_context_create($params);
$response = file_get_contents('https://api.expresspigeon.com/lists/{list_id}/upload', FILE_TEXT, $ctx);
    1
2
3

    require 'lib/expresspigeon-ruby'

res = ExpressPigeon::API.lists.upload(list_id, '/tmp/contacts.csv')
    1
2
3
4

    from expresspigeon import ExpressPigeon
    
api = ExpressPigeon()
response = api.lists.upload({list_id}, "/path/to/list.csv")

    The example above uses list_id in the URL. Please, make a note of it. The list.csv is a name of a local file filled with new or existing contacts.

    Example Response

    1
2
3
4
5
6

    {
    "status": "success",
    "code": 200,
    "message": "file uploaded successfully",
    "upload_id": 1
}

    Processing uploaded lists takes some time, therefore after a successful upload call, you might need to check status of the upload. The upload_id should be used for checking the status your upload. Please, see a section below for more information.

    Check the Status of List Upload

    GET https://api.expresspigeon.com/lists/upload_status/{id}

    Checks status of upload. If the upload was finished a detailed report is returned.

    Request parameters

    Parameter Required Description
    id Yes The id of a list uploaded(this id was returned from "Upload contacts into list")

    Example Request

    1
2

    curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/lists/upload_status/{upload_id}'
    1
2
3
4
5
6
7

    import org.javalite.http.Http;
import static org.javalite.common.JsonHelper.toMap;

String response = Http.get("https://api.expresspigeon.com/lists/upload_status/{upload_id}")
        .header("X-auth-key", AUTH_KEY)
        .text();
Map<String, Object> result = toMap(response);
    1
2
3
4
5
6
7
8
9

    $options = array(
  'http' => array(
    'method' => 'GET',
    'header' => "X-auth-key: 00000000-0000-0000-0000-000000000000\r\n"
    )
);
$context = stream_context_create($options);
$result = file_get_contents('https://api.expresspigeon.com/lists/upload_status/{upload_id}', false, $context);
$response = json_decode($result);
    1
2
3

    require 'expresspigeon-ruby'

puts ExpressPigeon::API.lists.upload_status list_id
    1
2
3
4

    from expresspigeon import ExpressPigeon
    
api = ExpressPigeon()
response = api.lists.upload_status({upload_id})

    Example Response

    If upload was finished you will get a report

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

    {
    "message": "file upload completed",
    "status": "success",
    "code": 200,
    "report": {
        "completed": true,
        "failed": false,
        "suppressed": 0,
        "skipped": 0,
        "list_id": 1,
        "list_name": "Active customers",
        "merged": 1,
        "imported": 1
    }
}

    If upload is still in progress you will get

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

    {
    "message": "file upload in progress",
    "status": "success",
    "code": 200,
    "report": {
        "completed": false,
        "failed": false,
        "suppressed": 0,
        "skipped": 0,
        "list_id": 1,
        "list_name": "Active customers",
        "merged": 0,
        "imported": 0
    }
}