Developers

With PHP

Setting up PostageApp in PHP is very simple and can be completed in a matter of minutes. If you already have an application that sends emails using the PHP Mail function, you will be able to keep most of the code you already have!

Here is a list of what you should do before you start:

  1. Create a PostageApp account.
  2. Create a project in your PostageApp account, take note of the API key for that particular project.

Create a Configuration File

File name: postageapp_config.inc

<?php
  # Setup Postage configuration
  if(!defined('POSTAGE_HOSTNAME')) define ('POSTAGE_HOSTNAME', 'https://api.postageapp.com');
  if(!defined('POSTAGE_API_KEY')) define ('POSTAGE_API_KEY', 'ENTER YOUR API KEY HERE');
?>

This configuration file is a simple copy and paste job for most users; it defines the location of the PostageApp API and selects the project you are sending emails with using the API key.

NOTE: Be sure to replace ENTER YOUR API KEY HERE with your API key!

Create a PostageApp Class

File name: postageapp_class.inc

<?php
  // Replace 'postageapp_config.inc' with the name of the PostageApp
  // config file you have created
  require_once('postageapp_config.inc');

  class PostageApp
  {
    // Sends a message to Postage App
    function mail($recipient, $subject, $mail_body, $header, $variables=NULL) {
      $content = array(
        'recipients'  => $recipient,
        'headers'     => array_merge($header, array('Subject' => $subject)),
        'variables'   => $variables,
        'uid'         => time()
      );
      if (is_string($mail_body)) {
        $content['template'] = $mail_body;
      } else {
        $content['content'] = $mail_body;
      }

      return PostageApp::post(
              'send_message',
              json_encode(
                array(
                  'api_key' => POSTAGE_API_KEY,
                  'arguments' => $content
                )
              )
             );
    }

    // Makes a call to the Postage App API
    function post($api_method, $content) {
      $ch = curl_init(POSTAGE_HOSTNAME.'/v.1.0/'.$api_method.'.json');
      curl_setopt($ch, CURLOPT_POSTFIELDS,  $content);
      curl_setopt($ch, CURLOPT_HEADER, false);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
      $output = curl_exec($ch);
      curl_close($ch);
      return json_decode($output);
    }
  }
?>

With this file, we create the PostageApp class that we will be calling when we want to send mail. It helps aggregate all of the information that we will be passing through during an API call, making our job much easier.

Making an API Call

<?php
 require_once('postageapp_class.inc');

 $to = 'me@example.com';

 // The subject of the message
 $subject = 'Postage App test email';

 // Setup some headers
 $header = array(
    'From'      => 'my_test@example.org',
    'Reply-to'  => 'my_test@example.org'
 );

 // The body of the message
 $mail_body = array(
    'text/plain' => 'Hello world in plain text',
    'text/html' => '<h1>Hello world</h1><p>in <b>HTML</b></p>'
 );

 // Send it all
 $ret = PostageApp::mail($to, $subject, $mail_body, $header);

 // Checkout the response
 if ($ret->response->status == 'ok') {
    echo '<br/><b>SUCCESS:</b>, An email was sent and the following response was received:';
 } else {
    echo '<br/><b>Error sending your email:</b> '.$ret->response->message;
 }

 echo '<pre style="text-align:left;">';
 print_r ($ret);
 echo '</pre>';
?>

The above code is an example of how to call the PostageApp mail function that was created in the postageapp_class.inc file.

$to determines the recipient of the email that you are sending out. $header is an array that inserts variables into the header, such as which email address the email will come from and which email recipients can reply to. $mail_body is also an array that determines the content of the email that you are sending out, which can be set through an API call or by using templates. $ret is what sends the entire email, and all of the code below that shows the status of email.

Using Templates

If you’d like to be sending emails using templates rather than filling in content, all you have to do is pass a string through to $mail_body or your equivalent email content variable. Here is an example API call using TemplateName as our template, with Subject:, From:, and Reply-to: headers already filled in on our PostageApp template:

<?php
 require_once('postageapp_class.inc');

 $to = 'me@example.com';

 // The body of the message
 $mail_body = 'TemplateName';

 // Send it all
 $ret = PostageApp::mail($to, $subject, $mail_body, $header);

 // Checkout the response
 if ($ret->response->status == 'ok') {
    echo '<br/><b>SUCCESS:</b>, An email was sent and the following response was received:';
 } else {
    echo '<br/><b>Error sending your email:</b> '.$ret->response->message;
 }

 echo '<pre style="text-align:left;">';
 print_r ($ret);
 echo '</pre>';
?>

If you want to override any of the headers, you just need to include it into your API call and it will take the arguments from your API call over the arguments from the template.

Access to the PostageApp API requires an account and API key. You can use the free "egg" plan to try it out and upgrade to paid plan any time you want.

Sign Up