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


Request Methods / Commands:


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
email 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
email 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

Detailed Notes:
  • 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
email 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

Detailed Notes:
  • 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
email 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
email 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
email 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

Detailed Notes:
  • 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
email 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

Detailed Notes: This API call is for testing only, do not use for full scale processing
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
email 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
email 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
email 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
email 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
email 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
email 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