Campaigns
Campaign API provides the same service as sending email campaigns from the website. A campaign consists of newsletter template, subject, from name, reply to, and a lists of contacts a campaign can be sent to.
Campaigns Creation
POST https://api.expresspigeon.com/campaigns
Creates a campaign. Invocation of this API will trigger sending or scheduling a new campaign. The content type of a request must be application/json.
Request parameters
| list_id |
Yes |
The id of a list the campaign is sent to. The list must be enabled. |
| template_id |
Yes |
The id of a newsletter template used for the campaign. |
| name |
Yes |
The name of a campaign. This name is for your reference only and will not be exposed to your audience. If you have Google Analytics turned on, this value will also be used for Google Analytics campaign. |
| from_name |
Yes |
This parameter is displayed as "From" field in the email program when your recipients view your message. Use this value to clearly state your name or name of your organization. |
| reply_to |
Yes |
This parameter specifies the email address which will be getting replies from your recipients should they choose to reply. The reply_to should be a valid email address. |
| subject |
Yes |
The subject of a newsletter |
| google_analytics |
Yes |
Indicates whether Google Analytics should be enabled for a campaign. Should be true or false. |
| schedule_for |
No |
Specifies what time a campaign should be sent. If it is provided the campaign will be scheduled to this time, otherwise campaign is sent immediately. The schedule_for must be in ISO date format and should be in the future. |
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
13
| curl -X POST -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
-H "Content-type: application/json" \
-d '{
"list_id": "1",
"template_id": "1",
"name": "My first newsletter",
"from_name": "Dave",
"reply_to": "dave@expresspigeon.com",
"subject": "Hello from Dave",
"google_analytics": "false",
"schedule_for": "2013-05-28T14:03:17.956+0300"
}' \
'https://api.expresspigeon.com/campaigns'
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
| 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("list_id", "1",
"template_id", "1",
"name", "My first newsletter",
"from_name", "Dave",
"reply_to", "dave@expresspigeon.com",
"subject", "Hello from Dave",
"google_analytics", "false",
"schedule_for", "2013-05-28T14:03:17.956+0300"));
String response = Http.post("https://api.expresspigeon.com/campaigns", 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
18
19
20
21
| $data = array(
'list_id' => '1',
'template_id' => '1',
'name' => 'My first newsletter',
'from_name' => 'Dave',
'reply_to' => 'dave@expresspigeon.com',
'subject' => 'Hello from Dave',
'google_analytics' => 'false',
'schedule_for' => '2013-05-28T14:03:17.956+0300'
);
$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/campaigns', false, $context);
$response = json_decode($result);
|
1
2
3
4
5
| require 'expresspigeon-ruby'
resp = ExpressPigeon::API.campaigns.send(:list_id => list_id, :template_id => template_id,
:name => 'My Campaign', :from_name => 'John', :reply_to => reply_to,
:subject => 'Hello, there!', :google_analytics => false)
|
1
2
3
4
5
6
7
8
| from expresspigeon import ExpressPigeon
api = ExpressPigeon()
response = api.campaigns.schedule(list_id=1, template_id=1, name="My first newsletter",
from_name="Dave",
reply_to="dave@expresspigeon.com", subject="Hello from Dave",
google_analytics=False,
schedule_for="2013-05-28T14:03:17.956+0300")
|
Example Response
1
2
3
4
5
6
| {
"status": "success",
"code": 200,
"message": "new campaign created successfully",
"campaign_id": 1
}
|
Delete a Campaign
DELETE https://api.expresspigeon.com/campaigns/{id}
Removes a campaign with a given id. Only scheduled campaigns can be deleted. Those that have already been sent cannot be deleted.
Request parameters
| id |
Yes |
The id of a campaign to be removed. |
Example Request
1
2
| curl -X DELETE -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns/2'
|
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/campaigns/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/campaigns/2', false, $context);
$response = json_decode($result);
|
1
2
3
| require 'expresspigeon-ruby'
resp = ExpressPigeon::API.campaigns.delete campaign_id
|
1
2
3
4
| from expresspigeon import ExpressPigeon
api = ExpressPigeon()
response = api.campaigns.delete(2)
|
Example Response
1
2
3
4
5
| {
"status": "success",
"code": 200,
"message": "campaign 1 was deleted"
}
|
List Campaigns
GET https://api.expresspigeon.com/campaigns
Returns a list of at most 1000 created campaigns, to get the next batch use from_id parameter.
Request parameters
| from_id |
No |
Id from where to get the next batch, e.g. the last id from the previous call |
| from |
No |
Start of the sending period (UTC, example: 2013-03-16T10:00:00.000+0000) |
| to |
No |
End of the sending period (UTC, example: 2013-03-16T20:00:00.000+0000) |
Example Request
1
2
| curl -X GET -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns'
|
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/campaigns")
.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/campaigns', false, $context);
$response = json_decode($result);
|
1
2
3
| require 'expresspigeon-ruby'
campaigns = ExpressPigeon::API.campaigns.all
|
1
2
3
4
| from expresspigeon import ExpressPigeon
api = ExpressPigeon()
response = api.campaigns.get_all()
|
Example Response
1
2
3
4
5
6
7
8
9
10
11
12
| {
"total": 1123,
"id": 456,
"send_time": "2013-09-20T11:29:57.000+0000",
"template_name": "Bob's standard newsletter",
"template_id": 123,
"reply_to": "bob@example.net",
"from_name": "Bobby",
"subject": "Bob's newsletter #34",
"name": "Bob's campaign #34",
"list_id": 123
}
|
Report for a Single Campaign
GET https://api.expresspigeon.com/campaigns/{campaign_id}
Returns a report for a campaign by campaign id.
Request parameters
| campaign_id |
Yes |
Campaign id the report is generated for. |
Example Request
1
2
| curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns/1'
|
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/campaigns/1")
.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/campaigns/1', false, $context);
$response = json_decode($result);
|
1
2
3
| require 'expresspigeon-ruby'
report = ExpressPigeon::API.campaigns.report campaign_id
|
1
2
3
4
| from expresspigeon import ExpressPigeon
api = ExpressPigeon()
response = api.campaigns.report(1)
|
Example Response
1
2
3
4
5
6
7
8
9
| {
"unsubscribed": 0,
"delivered": 3,
"in_transit": 0,
"bounced": 0,
"spam": 0,
"clicked": 2,
"opened": 3
}
|
Get All Subscribers for Campaign
GET https://api.expresspigeon.com/campaigns/{campaign_id}/all_subscribers
Returns an array of object(s) with email and id of all subscribers for a campaign.
Request parameters
| campaign_id |
Yes |
Campaign id to get all subscribers. |
Example Request
1
2
| curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns/1/all_subscribers'
|
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/campaigns/1/all_subscribers")
.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/campaigns/1/all_subscribers', false, $context);
$response = json_decode($result);
|
1
2
3
4
| from expresspigeon import ExpressPigeon
api = ExpressPigeon()
response = api.campaigns.all_subscribers(1)
|
Example Response
1
2
3
4
5
6
7
8
9
10
| [{
"id": "1",
"email": "bob@example.net",
"timestamp": "2013-09-20T11:29:57.000+0000"
},
{
"id": "2",
"email": "tob@example.net",
"timestamp": "2013-09-20T11:29:59.000+0000"
}]
|
GET https://api.expresspigeon.com/campaigns/{campaign_id}/delivered
Returns an array of object(s) with email and id of delivered contacts from a campaign.
Request parameters
| campaign_id |
Yes |
Campaign id the delivered contacts are found for. |
Example Request
1
2
| curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns/1/delivered'
|
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/campaigns/1/delivered")
.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/campaigns/1/delivered', false, $context);
$response = json_decode($result);
|
1
2
3
4
| from expresspigeon import ExpressPigeon
api = ExpressPigeon()
response = api.campaigns.delivered(1)
|
Example Response
1
2
3
4
5
6
7
8
9
10
| [{
"id": "1",
"email": "bob@example.net",
"timestamp": "2013-09-20T11:29:57.000+0000"
},
{
"id": "2",
"email": "tob@example.net",
"timestamp": "2013-09-20T11:29:59.000+0000"
}]
|
Get Opened Events for a Campaign
GET https://api.expresspigeon.com/campaigns/{campaign_id}/opened
Returns an array of opened events from a campaign.
Request parameters
| campaign_id |
Yes |
Campaign id the opened events are found for. |
Example Request
1
2
| curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns/1/opened'
|
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/campaigns/1/opened")
.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/campaigns/1/opened', false, $context);
$response = json_decode($result);
|
1
2
3
| require 'expresspigeon-ruby'
report = ExpressPigeon::API.campaigns.opened campaign_id
|
1
2
3
4
| from expresspigeon import ExpressPigeon
api = ExpressPigeon()
response = api.campaigns.opened(2)
|
Example Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| [{
"timestamp": "2013-09-20T11:29:57.000+0000",
"ip_address": "127.0.0.1",
"email": "bob@example.net",
"event_type": "opened",
"user_agent": "Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)"
},
{
"timestamp": "2014-01-15T13:34:27.000+0000",
"ip_address": "127.0.0.1",
"email": "tob@example.net",
"event_type": "opened",
"user_agent": "Mozilla/5.0 (X11; Linux i686) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1650.63 Safari/537.36",
}]
|
Get Clicked Events for Campaign
GET https://api.expresspigeon.com/campaigns/{campaign_id}/clicked
Returns an array of clicked events from a campaign.
Request parameters
| campaign_id |
Yes |
Campaign id the clicked events are found for. |
Example Request
1
2
| curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns/1/clicked'
|
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/campaigns/1/clicked")
.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/campaigns/1/clicked', false, $context);
$response = json_decode($result);
|
1
2
3
| require 'expresspigeon-ruby'
clicked = ExpressPigeon::API.campaigns.clicked campaign_id
|
1
2
3
4
| from expresspigeon import ExpressPigeon
api = ExpressPigeon()
response = api.campaigns.clicked(2)
|
Example Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| [{
"timestamp": "2014-01-15T13:34:27.000+0000",
"ip_address": "127.0.0.1",
"email": "bob@example.net",
"event_type": "clicked",
"user_agent": "Mozilla/5.0 (X11; Linux i686) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1650.63 Safari/537.36",
"url":"http://example.net"
},
{
"timestamp": "2014-01-15T13:34:32.000+0000",
"ip_address":"127.0.0.1",
"email":"tob@example.net",
"event_type":"clicked",
"user_agent":"Mozilla/5.0 (X11; Linux i686) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1650.63 Safari/537.36",
"url":"http://example.net/home"
}]
|
GET https://api.expresspigeon.com/campaigns/{campaign_id}/non_opens
Returns an array of object(s) with email and id of contacts from a campaign who did not open email.
Request parameters
| campaign_id |
Yes |
Campaign id to get non-opens. |
Example Request
1
2
| curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns/1/non_opens'
|
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/campaigns/1/non_opens")
.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/campaigns/1/non_opens', false, $context);
$response = json_decode($result);
|
1
2
3
4
| from expresspigeon import ExpressPigeon
api = ExpressPigeon()
response = api.campaigns.non_opens(1)
|
Example Response
1
2
3
4
5
6
7
8
| [{
"id": "1",
"email": "bob@example.net"
},
{
"id": "2",
"email": "tob@example.net"
}]
|
GET https://api.expresspigeon.com/campaigns/{campaign_id}/bounced
Returns an array of object(s) with email and id of bounced contacts from a campaign.
Request parameters
| campaign_id |
Yes |
Campaign id the bounced contacts are found for. |
Example Request
1
2
| curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns/1/bounced'
|
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/campaigns/1/bounced")
.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/campaigns/1/bounced', false, $context);
$response = json_decode($result);
|
1
2
3
| require 'expresspigeon-ruby'
bounced = ExpressPigeon::API.campaigns.bounced campaign_id
|
1
2
3
4
| from expresspigeon import ExpressPigeon
api = ExpressPigeon()
response = api.campaigns.bounced(1)
|
Example Response
1
2
3
4
5
6
7
8
9
10
11
12
| [{
"id": "1",
"email": "bob@example.net",
"timestamp": "2013-09-20T11:29:57.000+0000",
"type": "soft"
},
{
"id": "2",
"email": "tob@example.net",
"timestamp": "2013-09-20T11:29:59.000+0000",
"type": "hard"
}]
|
GET https://api.expresspigeon.com/campaigns/{campaign_id}/unsubscribed
Returns an array of object(s) with email and id of unsubscribed contacts from a campaign.
Request parameters
| campaign_id |
Yes |
Campaign id the unsubscribed contacts are found for. |
Example Request
1
2
| curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns/1/unsubscribed'
|
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/campaigns/1/unsubscribed")
.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/campaigns/1/unsubscribed', false, $context);
$response = json_decode($result);
|
1
2
3
| require 'expresspigeon-ruby'
unsubscribed = ExpressPigeon::API.campaigns.unsubscribed campaign_id
|
1
2
3
4
| from expresspigeon import ExpressPigeon
api = ExpressPigeon()
response = api.campaigns.unsubscribed(1)
|
Example Response
1
2
3
4
5
6
7
8
9
10
| [{
"id": "1",
"email": "bob@example.net",
"timestamp": "2013-09-20T11:29:57.000+0000"
},
{
"id": "2",
"email": "tob@example.net",
"timestamp": "2013-09-20T11:29:59.000+0000"
}]
|
GET https://api.expresspigeon.com/campaigns/{campaign_id}/spam
Returns an array of object(s) with email and id of spam contacts from a campaign.
Request parameters
| campaign_id |
Yes |
Campaign id the spam contacts are found for. |
Example Request
1
2
| curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns/1/spam'
|
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/campaigns/1/spam")
.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/campaigns/1/spam', false, $context);
$response = json_decode($result);
|
1
2
3
| require 'expresspigeon-ruby'
spam = ExpressPigeon::API.campaigns.spam campaign_id
|
1
2
3
4
| from expresspigeon import ExpressPigeon
api = ExpressPigeon()
response = api.campaigns.spam(1)
|
Example Response
1
2
3
4
5
6
7
8
9
10
| [{
"id": "1",
"email": "bob@example.net",
"timestamp": "2013-09-20T11:29:57.000+0000"
},
{
"id": "2",
"email": "tob@example.net",
"timestamp": "2013-09-20T11:29:59.000+0000"
}]
|