Postal API
Welcome to the Postal Parrot API documentation. All API requests will be made via an HTTP POST submission. Below is a general breakdown of a request:
My API Information
Description | Value |
Domain | https://www.postalparrot.com/postal_server.php |
api_user | Please Login for information |
api_hash | Please Login for information |
Download Examples / Files
All API requests require a method to POST the information to the API server, you can use methods like CURL or utilizing our in house HTTP class.
Below are some files available for download.
All examples require HTTP class file (or CURL):
class.http.php
Examples:
add_creative contact_statistics create_account create_creative_and_send kiss - TESTING ONLY list_statistics migrate_lists opt_in opt_in_to_company opt_out opt_out_of_company return_creatives return_lists_for_company send_creative_to_emails send_creative_to_list update_creative
All files in one simple download:
All Examples in one file
PHP - Request Methods / Commands:
Field | Explained | Required? | Example |
api_user | Username assigned to your account. | Yes | some_username |
api_hash | 40 charachter string, sha1 hash provided to you for authentication with the api | Yes | aa2c86aec7d59b67854c237c8d0cf12c08879d9e |
api_requests | This is a serialized php array (index by numeric values), each item in this main array should contain an API command "cmd" with its associated data fields. API commands consist of a php associative array where the field names are textual (see below). | Yes | a:2:{s:3:"cmd";s:4:"kiss";s:4:"data";a:5:{s:2:"to";s:14:"test1@test.com";s:4:"from";s:14:"test2@test.com";s:7:"subject";s:27:"TESTING KISS METHOD w/ HTML";s:4:"text";s:24:"this is the text portion";s:4:"html";s:67:"this is the html portion, This one is going to Gmail.";}} |
Example of possible requests:
(notice, multiple request commands may be sent in a single $api_requests array)
$api_requests[] = array(
'cmd' => 'kiss'
, 'data' => array(
'to' => 'test1@test.com'
, 'from' => 'test2@test.com'
, 'subject' => 'TESTING KISS METHOD w/ HTML'
, 'text' => 'this is the text portion'
, 'html' => '<b>this is the <u>html</u> portion</b>, This one is going to Gmail.'
)
);
$api_requests[] = array(
'cmd' => 'kiss'
, 'data' => array(
'to' => 'test3@test.biz'
, 'from' => 'test4@test.com'
, 'subject' => 'to holicom'
, 'html' => 'Testing <b>2</b> messages at the same time. This one is going to HoliBiz.'
)
);
Example Usage:
require_once('class.http.php');
$http = new C_http();
$http->set_post_data( 'api_user', $api_user );
$http->set_post_data( 'api_hash', $api_hash );
$http->set_post_data( 'api_requests', serialize($api_requests) );
$http_response = $http->post($api_url );
$api_responses = @unserialize($http_response);
XML - Request Methods / Commands:
Field | Explained | Required? | Example |
api_user | Username assigned to your account. | Yes | <api_user>some_username</api_user> |
api_hash | 40 charachter string, sha1 hash provided to you for authentication with the api | Yes | <api_hash>aa2c86aec7d59b67854c237c8d0cf12c08879d9e</api_hash> |
api_requests | This is the XML format for multiple requests (see below). | Yes |
<api_request> <cmd>kiss</cmd> <data> <to>somebody@somewhere.com</to> <from>you@yoursite.com</from> <subject>Testing</subject> <text>Testing 1. 2.. 3...</text> </data> </api_request> |
Example of possible requests:
(notice, multiple request commands may be sent in a single request)
<?xml version='1.0'?>
<api_requests>
<api_user>some_username</api_user>
<api_hash>aa2c86aec7d59b67854c237c8d0cf12c08879d9e</api_hash>
<api_request>
<cmd>kiss</cmd>
<data>
<to>test1@test.com</to>
<from>test2@test.com</from>
<subject>TESTING KISS METHOD w/ HTML</subject>
<text>this is the text portion</text>
<html><b>this is the <u>html</u> portion</b>, This one is going to Gmail.</html>
</data>
</api_request>
<api_request>
<cmd>kiss</cmd>
<data>
<to>test3@test.com</to>
<from>test4@test.com</from>
<subject>to holicom</subject>
<html>Testing <b>2</b> messages at the same time. This one is going to HoliBiz.</html>
</data>
</api_request>
</api_requests>
Example Usage:
require_once('class.http.php');
$http = new C_http();
$http->set_request_header( 'Content-Type', 'text/xml; charset=ISO-8859-1' );
$http->set_request_body( $xmlstr );
$api_responses = $http->post("https://www.postalparrot.com/postal_server.php");
Changelog
- Author: j0zf 2010.12.24
- - Initial Document Created
- Author: philip 2011.09.27
- - More API documentation added
- Author: philip 2012.03.07
- - Version 1.0 officially released
- Author: philip 2012.05.22
- - API documentation updated, examples added for download
- account_statistics
- add_creative
- add_drip_campaign
- bounce_statistics
- campaign_statistics
- campaign_statistics_summary
- company_list_association_by_email
- contact_statistics
- create_account
- create_creative_and_send
- delete_creative
- drip_modifications
- drip_statistics
- drip_statistics_detailed
- email_statistics
- kiss
- list_statistics
- migrate_lists
- opt_in
- opt_in_to_company
- opt_out
- opt_out_of_company
- process_event_sync
- process_queue
- process_queue_v2
- return_creatives
- return_lists_for_company
- send_creative_to_emails
- send_creative_to_list
- update_creative
- update_multiple_contacts
Command: drip_statistics
Return information about drip campaigns associated to a list
Field | Explained | Required? | Example |
cmd | Command "drip_statistics", Return information about drip campaigns associated to a list | Yes | drip_statistics |
Command: drip_statistics_detailed
Return information about drip campaigns
Field | Explained | Required? | Example |
cmd | Command "drip_statistics_detailed", Return information about drip campaigns | Yes | drip_statistics_detailed |
drip_id | The id of the drip | Yes | 28 |
Command: process_queue
A process that will allow a large supply of api_requests to be delivered at once, for more information contact us.
Field | Explained | Required? | Example |
cmd | Command "process_queue", A process that will allow a large supply of api_requests to be delivered at once, for more information contact us. | Yes | process_queue |
Command: create_account
Creates a new account within the system
Field | Explained | Required? | Example |
cmd | Command "create_account", Creates a new account within the system | Yes | create_account |
username | Pick a username between 7 and 15 characters, alphanumeric, and _'s only | Yes | bob_smith |
password | Pick a password between 7 and 15 characters, containing at least 1 number, 1 lowercase letter and 1 uppercase letter. | Yes | ??? |
first_name | Your First Name | Yes | Bob |
last_name | Your Last Name | Yes | Smith |
Your Email Address | Yes | example@domain.com | |
company | Your Company Name | Yes | Apogee Invent, Inc. |
address | Your Address | Yes | 1600 Pennsylvania Avenue |
city | Your City | Yes | Washington |
state | Your State | Yes | D.C. |
zip | Your Zip / Postal Code | Yes | 90210 |
from_email | The email address you wish to send emails from, if you have a private domain, please use this | Yes | example@domain.com |
Command: account_statistics
Return statistics on email address
Field | Explained | Required? | Example |
cmd | Command "account_statistics", Return statistics on email address | Yes | account_statistics |
A standard email address | Yes | example@domain.com |
Command: add_creative
Create a new creative
Field | Explained | Required? | Example |
cmd | Command "add_creative", Create a new creative | Yes | add_creative |
creative_name | The name of the creative | Yes | March Newsletter |
subject | The subject of the creative | Yes | March Newsletter, Sign up Now! |
html | The html of the creative, will support actual HTML, not just text | Yes | <b>This is going to be a fun month!!</b> |
list_name | The name of the list | No, if list_id is provided | March Newsletter |
list_id | The id of the list, if known | No, if list_name is provided | 79 |
Command: add_drip_campaign
Creates a new drip campain, does not add any creatives to campaign, simply the placeholder campaign
Field | Explained | Required? | Example |
cmd | Command "add_drip_campaign", Creates a new drip campain, does not add any creatives to campaign, simply the placeholder campaign | Yes | add_drip_campaign |
list_name | The name of the list | No, if list_id is provided | March Newsletter |
list_id | The id of the list, if known | No, if list_name is provided | 79 |
campaign_name | An optional name associated with this mailing | No | Facebook Banner |
Command: bounce_statistics
Return information about bounces
- If you do not provide a date range, the date range will be for the entire current month only.
- If you only provide a beg_date or end_date, the range will cease at the beginning or end of the month, respectively.
- A Maximum of 500 records will be provided. If more than 500 records exist, narrow your search parameters.
- All times returned are in 'Central' time format.
Field | Explained | Required? | Example |
cmd | Command "bounce_statistics", Return information about bounces | Yes | bounce_statistics |
campaign_name | The name of the campaign | No | Campaign Name |
list_name | The name of the list | No | List Name |
creative_name | The name of the creative | No | Creative Name |
The email address | No | example@abc.com | |
beg_date | The beginning date (format: YYYY-MM-DD HH:MM:SS) | Yes, if end_date is supplied | 2014-01-01 00:00:00 |
end_date | The end date (format: YYYY-MM-DD HH:MM:SS) | Yes, if beg_date is supplied | 2014-01-31 23:59:59 |
Command: campaign_statistics
Return information about the campaign
- If you do not provide a date range, the date range will be for the entire current month only.
- If you only provide a beg_date or end_date, the range will cease at the beginning or end of the month, respectively.
- A Maximum of 500 records will be provided. If more than 500 records exist, narrow your search parameters.
- All times returned are in 'Central' time format.
Field | Explained | Required? | Example |
cmd | Command "campaign_statistics", Return information about the campaign | Yes | campaign_statistics |
campaign_name | The name of the campaign | Yes | Campaign Name |
list_name | The name of the list | No | List Name |
creative_name | The name of the creative | No | Creative Name |
The email address | No | example@abc.com | |
beg_date | The beginning date (format: YYYY-MM-DD HH:MM:SS) | Yes, if end_date is supplied | 2014-01-01 00:00:00 |
end_date | The end date (format: YYYY-MM-DD HH:MM:SS) | Yes, if beg_date is supplied | 2014-01-31 23:59:59 |
Command: campaign_statistics_summary
Return information about your campaigns
Field | Explained | Required? | Example |
cmd | Command "campaign_statistics_summary", Return information about your campaigns | Yes | campaign_statistics_summary |
campaign_name | The name of the campaign | No | Campaign Name |
Command: company_list_association_by_email
Return list associations based on email address
Field | Explained | Required? | Example |
cmd | Command "company_list_association_by_email", Return list associations based on email address | Yes | company_list_association_by_email |
Command: contact_statistics
Return statistics on email address
Field | Explained | Required? | Example |
cmd | Command "contact_statistics", Return statistics on email address | Yes | contact_statistics |
A standard email address | Yes | example@domain.com |
Command: create_creative_and_send
Create a new creative & send to email addresses
Field | Explained | Required? | Example |
cmd | Command "create_creative_and_send", Create a new creative & send to email addresses | Yes | create_creative_and_send |
html | The html of the creative, will support actual HTML, not just text | Yes | <b>This is going to be a fun month!!</b> |
list_name | The name of the list | No, if list_id is provided | March Newsletter |
list_id | The id of the list, if known | No, if list_name is provided | 79 |
A standard email address | Yes | example@domain.com | |
campaign_name | An optional name associated with this mailing | No | Facebook Banner |
Command: delete_creative
Remove a creative
Field | Explained | Required? | Example |
cmd | Command "delete_creative", Remove a creative | Yes | delete_creative |
creative_name | The name of the creative | Yes | March Newsletter |
creative_id | The id of the creative | Yes | 1353 |
Command: drip_modifications
Make modifications to the drip campaign
Field | Explained | Required? | Example |
cmd | Command "drip_modifications", Make modifications to the drip campaign | Yes | drip_modifications |
Command: email_statistics
Return information about emails
- If you do not provide a date range, the date range will be for the entire current month only.
- If you only provide a beg_date or end_date, the range will cease at the beginning or end of the month, respectively.
- A Maximum of 500 records will be provided. If more than 500 records exist, narrow your search parameters.
- All times returned are in 'Central' time format.
Field | Explained | Required? | Example |
cmd | Command "email_statistics", Return information about emails | Yes | email_statistics |
campaign_name | The name of the campaign | No | Campaign Name |
list_name | The name of the list | No | List Name |
creative_name | The name of the creative | No | Creative Name |
The email address | No | example@abc.com | |
beg_date | The beginning date (format: YYYY-MM-DD HH:MM:SS) | Yes, if end_date is supplied | 2014-01-01 00:00:00 |
end_date | The end date (format: YYYY-MM-DD HH:MM:SS) | Yes, if beg_date is supplied | 2014-01-31 23:59:59 |
Command: kiss
Outdated api request, simply for testing structure
Field | Explained | Required? | Example |
cmd | Command "kiss", Outdated api request, simply for testing structure | Yes | kiss |
html | html body of the message. If this is present then most email clients will not display the "text" body of the message from the above field. | No | <b>Testing 1.2..3...</b> |
to | Text field with a single destination email address. | Yes | example@domain.com |
from | source email address | Yes | you@someplace.com |
subject | the emails subject line | Yes | A subject line |
text | text body of message | No | this is the text portion |
Command: list_statistics
Return list of email addresses assigned to a list
Field | Explained | Required? | Example |
cmd | Command "list_statistics", Return list of email addresses assigned to a list | Yes | list_statistics |
list_name | The name of the list | No, if list_id is provided | March Newsletter |
list_id | The id of the list, if known | No, if list_name is provided | 79 |
Command: migrate_lists
Add an email to a list, Force subscribed status of existing email address
Field | Explained | Required? | Example |
cmd | Command "migrate_lists", Add an email to a list, Force subscribed status of existing email address | Yes | migrate_lists |
A standard email address | Yes | example@domain.com | |
original_list_name | The name of the list the email address is assigned to | Yes | Daily Members |
list_name | The name of the list the email address is going to be | Yes | Daily Members |
vars | A list of variables associated with a contact, first_name, last_name, etc... In the form of var_XXXXXX where XXXXXX is the label of the variable |
No | var_first_name => Fred var_last_name => Smith var_city => Washington |
Command: opt_in
Add an email to a list, Force subscribed status of existing email address
Field | Explained | Required? | Example |
cmd | Command "opt_in", Add an email to a list, Force subscribed status of existing email address | Yes | opt_in |
A standard email address | Yes | example@domain.com | |
list_name | The name of the list to assign the email address to | Yes | Daily Members |
vars | A list of variables associated with a contact, first_name, last_name, etc... In the form of var_XXXXXX where XXXXXX is the label of the variable |
No | var_first_name => Fred var_last_name => Smith var_city => Washington |
reason | A short description about the rationale behind the contact, newsletter, website, etc... | No | Newsletter Signup |
Command: opt_in_to_company
Set all email addresses to subscribed for that company
Field | Explained | Required? | Example |
cmd | Command "opt_in_to_company", Set all email addresses to subscribed for that company | Yes | opt_in_to_company |
A standard email address | Yes | example@domain.com |
Command: opt_out
Unsubscribes an email from a list
Field | Explained | Required? | Example |
cmd | Command "opt_out", Unsubscribes an email from a list | Yes | opt_out |
A standard email address | Yes | example@domain.com | |
list_name | The name of the list to assign the email address to | Yes | Daily Members |
reason | A short description about the rationale behind the contact, newsletter, website, etc... | No | Newsletter Signup |
Command: opt_out_of_company
Remove an email from all lists belonging to that company
Field | Explained | Required? | Example |
cmd | Command "opt_out_of_company", Remove an email from all lists belonging to that company | Yes | opt_out_of_company |
A standard email address | Yes | example@domain.com |
Command: process_event_sync
A process that will allow a large supply of events to be delivered at once, for more information contact us.
Field | Explained | Required? | Example |
cmd | Command "process_event_sync", A process that will allow a large supply of events to be delivered at once, for more information contact us. | Yes | process_event_sync |
Command: return_creatives
Return list of creatives for the company
Field | Explained | Required? | Example |
cmd | Command "return_creatives", Return list of creatives for the company | Yes | return_creatives |
list_name | The name of the list that creatives are tied to | No | Daily Members |
strict | A flag to determine if you want only that list's creatives, or if you want that list's as well as unassociated creatives. | No | Any Value, as long as provided |
Command: return_lists_for_company
Return list of lists associated to the company, their name, their count and if tied to a drip campaign
Field | Explained | Required? | Example |
cmd | Command "return_lists_for_company", Return list of lists associated to the company, their name, their count and if tied to a drip campaign | Yes | return_lists_for_company |
Command: send_creative_to_emails
Send an existing creative to email addresses
Field | Explained | Required? | Example |
cmd | Command "send_creative_to_emails", Send an existing creative to email addresses | Yes | send_creative_to_emails |
creative_name | The name of the creative | No, if creative_id is provided | March Newsletter |
creative_id | The id of the creative, returned as "postalparrotid" | No, if creative_name is provided | 312 |
A standard email address | Yes, if not sending to a list | example@domain.com | |
campaign_name | An optional name associated with this mailing | No | Facebook Banner |
Command: send_creative_to_list
Send out a pre-defined creative to a already existing list
Field | Explained | Required? | Example |
cmd | Command "send_creative_to_list", Send out a pre-defined creative to a already existing list | Yes | send_creative_to_list |
creative_name | The name of the creative | No, if creative_id is provided | March Newsletter |
creative_id | The id of the creative, returned as "postalparrotid" | No, if creative_name is provided | 312 |
list_name | The name of the list | No, if list_id is provided | March Newsletter |
list_id | The id of the list, if known | No, if list_name is provided | 79 |
list_expiration_time | The timestamp that the list will expire on, used for "dynamic lists" | No, only if wanting to force the list to expire | 1336569211 |
campaign_name | An optional name associated with this mailing | No | Facebook Banner |
Command: update_creative
Update an existing creative
Field | Explained | Required? | Example |
cmd | Command "update_creative", Update an existing creative | Yes | update_creative |
creative_name | The name of the creative | No, if creative_id is provided | March Newsletter |
creative_id | The id of the creative, returned as "postalparrotid" | No, if creative_name is provided | 312 |
html | The html of the creative, will support actual HTML, not just text | Yes | <b>This is going to be a fun month!!</b> |
Command: update_multiple_contacts
Internally used API Call, contact us for further information
Field | Explained | Required? | Example |
cmd | Command "update_multiple_contacts", Internally used API Call, contact us for further information | Yes | update_multiple_contacts |
Command: process_queue_v2
A process that will allow a large supply of api_requests to be delivered at once. This version responds back with each id completed. For more information contact us.
Field | Explained | Required? | Example |
cmd | Command "process_queue_v2", A process that will allow a large supply of api_requests to be delivered at once. This version responds back with each id completed. For more information contact us. | Yes | process_queue_v2 |