Postalparrot API Documentation

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:


Table of Contents


My API Information

Description Value
Domain https://www.postalparrot.com/postalparrot_server.php
api_user Please Login for information
api_hash Please Login for information
PHP XML

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:

$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);


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:

$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/postalparrot_server.php");

Request Methods / Commands:

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: 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 dev@apogeeinvent.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: 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 dev@apogeeinvent.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: 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 dev@apogeeinvent.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: 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

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 dev@apogeeinvent.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: 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

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 dev@apogeeinvent.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>

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: 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 dev@apogeeinvent.com

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: 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
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, if not sending to a list dev@apogeeinvent.com

Command: return_lists_for_company
Return list of lists associated to the company

Field Explained Required? Example
cmd Command "return_lists_for_company", Return list of lists associated to the company Yes return_lists_for_company

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 dev@apogeeinvent.com

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 dev@apogeeinvent.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 dev@apogeeinvent.com

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 dev@apogeeinvent.com


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