Getting started with the ExpressPigeon API

ExpressPigeon provides a set API Endpoints to be used by external developers and allows for easy integration with our system.

Our API is represented by a set of RESTful service end points. Common uses are covered, such as audience manipulation, replication and merge of newsletters, sending transactional emails, and others. We are constantly at work making our services better, and often make modifications and extend our APIs based on customer feedback. If you do not find what you are looking for, simply let us know, and will consider your request.

General Concepts

ExpressPigeon API uses HTTP requests for ease of integration. Such requests use HTTP methods: GET, POST, PUT and DELETE. For GET requests, input values are supplied as standard query string parameters. It should be easy to play with these using the address bar in browsers.

For POST, PUT and DELETE methods, you will need to send in a JSON document and expect a JSON document to be returned back. In essence, our API can be explained as:

JSON in / JSON out — REST API

As a result, for all cases when you need to send in JSON document, please set Content-type: application/json, and expect the same as output.

Security and Authentication

All API calls are secure and protected by SSL encryption and our HTTPs certificate.

In order to ensure authentication and authorization, all calls require so-called Authentication Key. This value must be provided as an HTTP header for POST, PUT and DELETE methods.

For GET requests, you have an option to provide it as an HTTP header, or as a request parameter. This is done for convenience, since it allows to play with GET requests using a browser.

Request parameter authentication key name: auth_key Authentication header name: X-auth-key

Location of the Authentication key is: Settings → Integrations, or directly at: https://expresspigeon.com/settings/integrations.

Error Codes & Responses

The ExpressPigeon API uses JSON format and returns appropriate HTTP response code for every request and response. When the ExpressPigeon API returns error message there is a meaningful explanation why the error is occurred. Most JSON documents returned as a response to an error condition also include HTTP status code in the body of JSON document. This is done for convenience.

Code Text Description
200 OK Successful request
400 Bad Request The request is invalid. See an error message for more details.
403 Forbidden The request is understood, but access is not allowed because of missing or incorrect "X-auth-key" header or "auth_key" parameter.
404 Not Found Requested URI or a resource not found
500 Internal Server Error In rare cases, there can be an issue with our API . If this happens, please write to us so that our team can investigate and fix the issue.

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

Parameter Required Description
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.


Curl example

        
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'
        
        
Select code

Example Response

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

Parameter Required Description
id Yes The id of a campaign to be removed.


Curl example

        
curl -X DELETE -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns/2'
        
        
Select code

Example Response

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

Parameter Required Description
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)


Curl example

        
curl -X GET -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns'
        
        
Select code

Example Response

            
[{
"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.



Curl example

        
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns/1'
        
        
Select code

Request parameters

Parameter Required Description
campaign_id Yes Campaign id the report is generated for.


Example Response

            
{
"unsubscribed": 0,
"delivered": 3,
"in_transit": 0,
"bounced": 0,
"spam": 0,
"clicked": 2,
"opened": 3
}
            
        

Get opened events for campaign

GET https://api.expresspigeon.com/campaigns/{campaign_id}/opened

Returns an array of opened events from a campaign.



Curl example

        
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns/1/opened'
        
        
Select code

Request parameters

Parameter Required Description
campaign_id Yes Campaign id the opened events are found for.


Example Response

            
[{
"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.



Curl example

            
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns/1/clicked'
            
        
Select code

Request parameters

Parameter Required Description
campaign_id Yes Campaign id the clicked events are found for.


Example Response

            
[{
"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 bounced contacts for campaign

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.



Curl example

            
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns/1/bounced'
            
        
Select code

Request parameters

Parameter Required Description
campaign_id Yes Campaign id the bounced contacts are found for.


Example Response

            
[{
"id": "1",
"email": "bob@example.net",
},
{
"id": "2",
"email": "tob@example.net",
}]
            
        

Get unsubscribed contacts for campaign

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.



Curl example

        
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns/1/unsubscribed'
        
        
Select code

Request parameters

Parameter Required Description
campaign_id Yes Campaign id the unsubscribed contacts are found for.


Example Response

            
[{
"id": "1",
"email": "bob@example.net",
},
{
"id": "2",
"email": "tob@example.net",
}]
            
        

Get spam contacts for campaign

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.



Curl example

        
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/campaigns/1/spam'
        
        
Select code

Request parameters

Parameter Required Description
campaign_id Yes Campaign id the spam contacts are found for.


Example Response

            
[{
"id": "1",
"email": "bob@example.net",
},
{
"id": "2",
"email": "tob@example.net",
}]
            
        

Contacts

Contacts end point allows you to create, read, update and delete contacts on your lists. A contact consists of required email and various standard and custom fields.

Read a single contact by email

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

Returns a single contact by email address.



Curl example

        
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/contacts?email=bob@example.net'
        
        
Select code

Request parameters

Parameter Required Description
email Yes Email of contact to be selected.


Example Response

            
{
"custom_fields": {
"my custom field": "custom value"
},
"first_name": "Bob",
"email": "bob@example.net",
"created_at": "2012-10-29T14:17:58.000+0000",
"updated_at": "2013-01-24T08:20:52.000+0000",
"status": "ENGAGED",
"lists": [{"id": 1}, {"id": 2}}]
}
            
        

Create or update contacts

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

JSON document represents a list of contacts to be created or updated. The email field is required. When updating a contact, list_id is optional, since the contact is uniquely identified by email across all lists.



Curl example

        
curl -X POST -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
-H "Content-type: application/json" \
-d '{
"list_id": 11,
"contacts": [{
"email": "john@doe.net",
"first_name": "John",
"last_name": "Doe"
},
{
"email": "jane@doe.net",
"first_name": "Jane",
"last_name": "Doe",
"custom_fields": { "relative": "john@doe.net" }
}]
}' \
'https://api.expresspigeon.com/contacts'
        
        
Select code

Request parameters

Parameter Required Description
contacts Yes JSON list represents contacts to be inserted or updated. The email field is required.
list_id No List id to add contacts to.


Example Response

            
{
"status" : "success",
"code" : 200,
"message" : "contacts created/updated successfully",
"contacts": [ "bob@example.net" ]
}
            
        

List of created/updated contact emails is returned for your convenience. If there is an issue with a contact (contact is suppressed, bad formatting. etc.), no changes are made to entire set of contacts and the call returns a parameter failed_contact_num which indicates the position of problem contact in the submitted document.

Delete a single contact

DELETE https://api.expresspigeon.com/contacts
NOTE: this call requires the HTTP DELETE method

Curl example

        
curl -X DELETE -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/contacts?email=bob@example.net'
        
        
Select code

Request parameters

Parameter Required Description
email Yes Contact email to be deleted
list_id No List id to remove contact from, if not provided, contact will be deleted from system


Example Response

            
{
"status" : "success",
"code" : 200,
"message" : "contact=bob@example.net deleted successfully"
}
            
        

Move contacts between lists

POST https://api.expresspigeon.com/contacts/move

JSON document represents a list of contacts to be moved between source and target lists. All fields are required.



Curl example

        
curl -X POST -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
-H "Content-type: application/json" \
-d '{
"source_list": 1,
"target_list": 2,
"contacts": [ "bob@example.net", "toby@example.net" ]
}' \
'https://api.expresspigeon.com/contacts/move'
        
        
Select code

Request parameters

Parameter Required Description
source_list Yes Source list id
target_list Yes Target list id
contacts Yes Contacts to be moved


Example Response

            
{
"status" : "success",
"code" : 200,
"message" : "contacts moved from list=1 to list=2"
}
            
        

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



Curl example

        
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/lists'
        
        
Select code

Example Response

            
[{
"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



Curl example

        
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'
        
        
Select code

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 Response

            
{
"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.



Curl example

        
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'
        
        
Select code

Request parameters

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


Example Response

            
{
"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.



Curl example

 
        curl -X DELETE -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/lists/2'
        
        
Select code

Request parameters

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


Example Response

            
{
"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.



Curl example

        
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/lists/123/csv'
        
        
Select code

Request parameters

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


Example Response

            
"Email", "First name", "Last name", "City", "Phone", "Company", "Title", "Address 1", "Address 2", "State", "Zip", "Country", "Date of birth"
"bob@example.net","Bob",,,,,,,,,,,
            
        

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.



Curl example

        
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'
        
        
Select code

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

            
{
"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.



Curl example

        
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/lists/upload_status/{upload_id}'
        
        
Select code

Request parameters

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


Example Response

If upload was finished you will get a report

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

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

Transactional emails made easy!

Contacts end point allows you to create, read, update and delete contacts on your lists. A contact consists of required email and various standard and custom fields.


Design

YOURCOMPANYLOGO
Hi, ${first_name}!

Your statement is ready to review online!


POST

            
{
"template_id": 123,
"reply_to": "john@acme.com",
"from": "John Doe",
"to": "jane@doe.com",
"subject": "Statement ready",
"merge_fields": {
  "first_name": "Jane"
}}
            
        

Result

YOURCOMPANYLOGO
Hi, Jane!

Your statement is ready to review online!



Transactional emails are sometimes called triggered emails. Unlike bulk emails, they are sent one at the time on per need basis and contain highly personalized content. Examples of triggered emails can be one-off messages, such as password reset, statement generated, etc.

Our Transactional API is a set of HTTP REST end points designed for implementation with external systems in order to send email as well as retrieving reporting data.



Messages

Sending Transactional emails requires that newsletter templates for these emails are created prior to sending. Such template can have merge fields, in a format ${field_name}. This feature allows a high degree of flexibility for message customization.

The newsletter to be sent can have a number of merge fields, with data for merging dynamically provided during a call.

Sending a single transactional email

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

JSON object represents a message to be sent.



Curl example

  
        curl -X POST -H "X-auth-key: 00000000-0000-0000-0000-000000000000"
-H "Content-type: application/json"
-d \
'{
    "template_id": 123,
    "reply_to": "john@example.net",
    "from": "John",
    "to": "jane@example.net",
    "subject": "Dinner served",
    "merge_fields": {
        "first_name": "John",
        "menu": "<table><tr><td>Burger:</td></tr><tr>$9.99<td></td></tr></table>"
        },
    "dictionaries": ["dict1","dict2"]
}'
'https://api.expresspigeon.com/messages'
        
        
Select code

Code above also shows that it is possible to inject HTML chunks into specific placeholders inside your email template.


NOTE: It is important to use only single quotes in injected HTML


Request parameters

Parameter Required Description
template_id Yes Newsletter template id to be sent
to Yes Email address to send message to
reply_to Yes Email address tp reply to
from Yes From name, such as your name or name of your organization
subject Yes Email message subject
merge_fields No Values for merge fields
view_online No Generates online version of sent message. We will host this generated message on our servers, default is false
click_tracking No Overwrites all URLs in email to point to http://clicks.expresspigeon.com for click tracking. Setting it to false will preserve all URLs intact, but click tracking will not be available, default is true
suppress_address No If true suppresses insertion of sender's physical address in the email, default is false
dictionaries No List of dictionaries to source merge fields from. Dictionary values override all other values (from merge_fields) in case of name collisions. See Dictionaries section for more information.


Example Response

            
{
"status": "success",
"code": 200,
"id": 1,
"message": "email queued"
}
            
        

In a call above, the id represents an ID of a message that was sent. You can use this value in order to get a report on status of this message. Please, see below on how to retrieve such a report.

Sending a message with attachment

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

Curl example

  
        curl -X POST https://api.expresspigeon.com/messages  \
            -H "Content-type: multipart/form-data" \
            -H "X-auth-key: 00000000-0000-0000-0000-000000000000"\
            -F template_id=123\
            -F reply_to='john@doe.com'\
            -F from='John Doe'\
            -F to='jane@doe.com'\
            -F subject='two attachments'\
            -F view_online=true\
            -F suppress_address=true\
            -F click_tracking=false\
            -F merge_fields='{"first_name": "Jane"}'\
            -F attachment=@attachment1.txt\
            -F attachment=@attachment2.txt
        
        
Select code

Code above shows how to include attachments. The paths to files can be absolute, or relative (as in this example).

Request parameters

Request parameters are the same as when sending a a single message without attachments.

Limitations are: maximum three attachments, each under 10kb in size.


Example Response

            
{
"status": "success",
"code": 200,
"id": 1,
"message": "email queued"
}
            
        

In a call above, the id represents an ID of a message that was sent. You can use this value in order to get a report on status of this message. Please, see below on how to retrieve such a report.

Report for a single message

GET https://api.expresspigeon.com/messages/{id}

Returns a report with properties of a sent message, such as 'delivered' or 'bounced', 'opened', 'clicked' etc.



Curl example

 
        curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/messages/1'
        
        
Select code

Request parameters

Parameter Required Description
id Yes Id of sent message


Example Response

            
{
"id": 1,
"email": "john@example.net",
"in_transit": false,
"delivered": true,
"bounced": false,
"opened": true,
"clicked": true,
"urls": [
    "http://example.net/buy_a_burger"
],
"spam": false,
"created_at": "2013-03-15T11:20:21.770+0000",
"updated_at": "2013-03-16T11:22:23.210+0000"
}
            
        

Report for multiple messages

GET https://api.expresspigeon.com/messages/{period}

Returns a report (ordered by id) for at most 1000 of transactional emails sent with this API, to get the next batch use from_id parameter.



Curl example

        
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/messages'
        
        
Select code

Request parameters

Parameter Required Description
start_date No Start of the reporting period (UTC, example: 2013-03-16T10:00:00.000+0000)
end_date No End of the reporting period (UTC, example: 2013-03-16T20:00:00.000+0000)
period No Predefined reporting period: last24hours, last_week, last_month
from_id No Id from where to get the next batch, e.g. the last id from the report


Example Response

            
[{
"id": 1,
"email": "john@example.net",
"in_transit": false,
"delivered": true,
"bounced": false,
"opened": true,
"clicked": true,
"urls": [
    "http://example.net/buy_a_burger"
],
"spam": false,
"created_at": "2013-03-15T11:20:21.770+0000",
"updated_at": "2013-03-16T11:22:23.210+0000"
},
{
"id": 2,
"email": "bob@example.net",
"in_transit": false,
"delivered": true,
"bounced": false,
"opened": false,
"clicked": false,
"urls": [],
"spam": false,
"created_at": "2013-04-15T11:20:21.770+0000",
"updated_at": "2013-04-16T11:22:23.210+0000"
}]
            
        

Templates

Copy template

POST https://api.expresspigeon.com/templates/{id}/copy

This feature allow developers to create a copy of an email template and at the same time merge data into a new version. It makes it possible to have the following workflow:

  1. Create a blank newsletter and add merge fields to it (using email editor)
  2. Make a new copy of this newsletter, and merge specific data into it using this API
  3. Send or schedule a new campaign with the API

Steps 2 and 3 can be done remotely with the API, without having to log into the website. Combined with ability to create new lists on the fly, and upload contacts, it provides an opportunity to build powerful marketing solutions.



Curl example

        
curl -X POST -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
-H "Content-type: application/json" \
-d '{
"name": "My new template",
"merge_fields":{
"menu": "<table class='report'><tr><td>Burger:</td></tr><tr>$9.99<td></td></tr></table>"
}
}' \
'https://api.expresspigeon.com/templates/123/copy'
        
        
Select code

NOTE: It is important to use only single quotes in injected HTML


Request parameters

Parameter Required Description
id Yes Template id to be used as a source
name Yes Name for a new template
merge_fields No Values of merge fields


Example Response

            
{
"status": "success",
"code": 200,
"message": "template copied successfully",
"template_id": 124
}
            
        

The template_id in the response document above is an ID of a newly created newsletter template which already contains all data merged.

Delete template

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

Delete single template by id



Curl example

        
curl -X DELETE -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/templates/123'
        
        
Select code

Request parameters

Parameter Required Description
id Yes Template id to be deleted


Example Response

            
{
"status": "success",
"code": 200,
"message": "template deleted successfully"
}
            
        

Autoresponders

Get all autoresponders

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

Returns an array of autoresponders.



Curl example

        
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/auto_responders'
        
        
Select code

Example Response

            
[{
    "auto_responder_parts": [{
        "auto_responder_part_id": 1,
        "subject": "My autoresponder",
        "template_id": 1
    }],
    "name": "My autoresponder",
    "auto_responder_id": 1
}]
            
        

Start for a contact

POST https://api.expresspigeon.com/auto_responders/{auto_responder_id}/start

This call starts an autoresponder for a contact.



Curl example

        
curl -X POST -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
-H "Content-type: application/json" \
-d '{"email": "bob@example.net"}' \
'https://api.expresspigeon.com/auto_responders/1/start'
        
        
Select code

Request parameters

Parameter Required Description
auto_responder_id Yes Autoresponder id to be started for a contact
email Yes Contact email


Example Response

            
{
"status": "success",
"code": 200,
"message": "auto_responder=1 started successfully for contact=bob@example.net"
}
            
        

Stop for a contact

POST https://api.expresspigeon.com/auto_responders/{auto_responder_id}/stop

This call stops an autoresponder for a contact.



Curl example

        
curl -X POST -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
-H "Content-type: application/json" \
-d '{"email": "bob@example.net"}' \
'https://api.expresspigeon.com/auto_responders/1/stop'
        
        
Select code

Request parameters

Parameter Required Description
auto_responder_id Yes Autoresponder id to be stopped for a contact
email Yes Contact email


Example Response

            
{
"status": "success",
"code": 200,
"message": "auto_responder=1 stopped successfully for contact=bob@example.net"
}
            
        

Report for a single autoresponder

GET https://api.expresspigeon.com/auto_responders/{auto_responder_id}

Returns a report for a single autoresponder by id.



Curl example

        
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/auto_responders/1'
        
        
Select code

Request parameters

Parameter Required Description
auto_responder_id Yes Autoresponder id for which this report is generated


Example Response

            
[{
"auto_responder_part_id": 9,
"delivered": 1,
"unsubscribed": 0,
"in_transit": 0,
"bounced": 0,
"spam": 0,
"clicked": 0,
"opened": 1
}]
            
        

Get bounced contacts for autoresponder part

GET https://api.expresspigeon.com/auto_responders/ {auto_responder_id}/{auto_responder_part_id}/bounced

Returns an array of object(s) with email and id of bounced contacts associated with this autoresponder part.



Curl example

        
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/auto_responders/1/2/bounced'
        
        
Select code

Request parameters

Parameter Required Description
auto_responder_id Yes Autoresponder id the bounced contacts are found for
auto_responder_part_id Yes Autoresponder part id the bounced contacts are found for


Example Response

            
[{"id": 1, "email": "bob@example.net"}, {"id": 2, "email": "tob@example.net"}]
            
        

Get unsubscribed contacts for autoresponder part

GET https://api.expresspigeon.com/auto_responders/ {auto_responder_id}/{auto_responder_part_id}/unsubscribed

Returns an array of object(s) with email and id of unsubscribed contacts associate with this autoresponder part.



Curl example

        
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/auto_responders/1/2/unsubscribed'
        
        
Select code

Request parameters

Parameter Required Description
auto_responder_id Yes Autoresponder id the unsubscribed contacts are found for
auto_responder_part_id Yes Autoresponder part id the unsubscribed contacts are found for


Example Response

            
[{"id": 1, "email": "bob@example.net"}, {"id": 2, "email": "tob@example.net"}]
            
        

Get spam contacts for autoresponder part

GET https://api.expresspigeon.com/auto_responders/ {auto_responder_id}/{auto_responder_part_id}/spam

Returns an array of object(s) with email and id of spam contacts associated with this autoresponder part.



Curl example

        
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/auto_responders/1/2/spam'
        
        
Select code

Request parameters

Parameter Required Description
auto_responder_id Yes Autoresponder id the spam contacts are found for
auto_responder_part_id Yes Autoresponder part id the spam contacts are found for


Example Response

            
[{"id": 1, "email": "bob@example.net"}, {"id": 2, "email": "tob@example.net"}]
            
        

Dictionaries

Dictionaries are a capability to store name/value pairs on your account to merge into templates. They remove the need to send the same data over and over to the API.

A single dictionary may represent a product with attributes, where each attribute name is some property of a product (name, description, price, URL to image, etc.). In other cases, a dictionary can be a set of internationalized messages, where each dictionary is a collection of messages in different languages (English, French, etc.)

Create a new dictionary

https://api.expresspigeon.com/dictionaries

You can create multiple dictionaries in a single API call.

Please, do not forget to set content-type to application/json



Curl example

        
curl -X POST -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
-H "Content-type: application/json"
-d \
'[{
"name": "sandwich1",
"values": {
    "name": "ORGANIC GRASS FED SIRLOIN",
    "price": "$7.00",
    "image": "http://yourdomain.com/contnet/sandwich1.png",
    "url": "http://yourdomain.com/sandwich1",
    "description": "certified organic grass fed sirloin, Swiss Gruyère cheese, vine tomatoes, organic mixed greens, caramelized organic onions and housemade horseradish aioli on organic bretzel baguette"
    }
},
{
"name": "sandwich2",
"values": {
    "name": "ORGANIC ROASTED TOFU",
    "price": "$4.99",
    "image": "http://yourdomain.com/contnet/sandwich1.png",
    "url": "http://yourdomain.com/sandwich2",
    "description": "certified organic smoked turkey, local white cheddar, fresh organic apple crisps, organic mixed greens and housemade roasted pepper aioli on organic bretzel baguette"
    }
}]'
'https://api.expresspigeon.com/dictionaries'
        
        
Select code

Request parameters

Parameter Required Description
name Yes Name of a new or existing dictionary
values Yes Collection of name/value pairs


Example Response

            
{
"code":200,
"ids":[123,456],
"message":"dictionaries created/updated successfully",
"status":"success"
}
            
        

Where 123 and 456 are IDs of created or updated dictionaries.

Listing dictionaries with UI

You can see and edit dictionaries using a browser. First, login into your account, and navigate to https://expresspigeon.com/dictionaries.

Enter * or a dictionary name into the search field and press Enter.

Listing dictionaries

https://api.expresspigeon.com/dictionaries

Allows to list multiple dictionaries.



Curl example

        
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/dictionaries'
        
        
Select code

Example Response

            
[{
"id":1,
"updated_at":"2014-05-14T21:58:31.000+0000",
"name":"dict1",
"created_at":"2014-05-14T21:58:31.000+0000"
},
{
"id":2,
"updated_at":"2014-05-14T21:58:31.000+0000",
"name":"dict2",
"created_at":"2014-05-14T21:58:31.000+0000"
}]
            
        

Get a single dictionary

https://api.expresspigeon.com/dictionaries

Lookup a single dictionary



Curl example

        
curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/dictionaries/dict_id'
        
        
Select code

Where "dict_id" is a dictionary ID.



Example Response

            
{
"id":1,
"values":[
    {"name":"product1","value":"Swing set"},
    {"name":"product2","value":"Weber grill"},
    {"name":"product3","value":"IPhone"},
    {"name":"product4","value":"Eye glasses"},
    {"name":"sale1","value":"30% off"},
    {"name":"sale2","value":"50% off"}],
"updated_at":"2014-05-14T21:58:31.000+0000",
"name":"dict1",
"created_at":"2014-05-14T21:58:31.000+0000"
}