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
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
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
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"
}
|
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
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"
|
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
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
}
}
|