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:


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_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: 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