Getting Started

Getting started with Postmark is very easy. Let's talk about pre-requisites:

Pre-requisites:

1. A Postmark Account: Sign up for a new account.
2. A "Server Token": Set up a new 'server' in your account.
3. A "Sender Signature": Create a sender signature.

Installation:

Postmark-PHP is available as a Composer package on Packagist.org.

To install it in your project, simply run:

composer require wildbit/postmark-php

After this runs successfully, you will want to include two classes in your application logic:

use Postmark\PostmarkClient;
use Postmark\Models\PostmarkException;

If you intend to use the Admin capabilities of the API, you may include the following class:

use Postmark\PostmarkAdminClient;

Sending your first email:

Postmark is designed to make sending email super easy, the following snippet shows how easy it is to get started:

//import the classes we'll be using and require the autoloader if it hasn't been already.
require_once('./vendor/autoload.php');
use Postmark\PostmarkClient;
use Postmark\Models\PostmarkException;

try{
  $client = new PostmarkClient("<server token>");
  $sendResult = $client->sendEmail("<sender signature>",
    "ben@example.com",
    "Hello from Postmark!",
    "This is just a friendly 'hello' from your friends at Postmark.");

  // Getting the MessageID from the response
  echo $sendResult->MessageID;

}catch(PostmarkException $ex){
  // If the client is able to communicate with the API in a timely fashion,
  // but the message data is invalid, or there's a server error,
  // a PostmarkException can be thrown.
  echo $ex->httpStatusCode;
  echo $ex->message;
  echo $ex->postmarkApiErrorCode;

}catch(Exception $generalException){
  // A general exception is thrown if the API
  // was unreachable or times out.
}

This is the bare-minimum to send an email using the Postmark client, but you can do a great deal more with the Postmark-PHP library. Take special note that you should replace <server token> with the token you obtained in item two of the pre-requisites, and replace <sender signature> with the signature you obtained from item three of the pre-requisites above.

About Responses from API Calls:

Most API calls return results that you will want to use in your application. Since your project may have coding styles related to when to use associative arrays versus object member access, our API responses return dynamic objects that can be used with either style of access, for example:

$id = 42;
$result = $client->getBounce($id);

//We can now access the members of the result through various syntaxes:

//Array or object access:
$result['dumpAvailable'];
$result->dumpAvailable;

//Case-insensitive, too:
$result['DuMpAvAilAbLe'];
$result->DumpAVAILABLE;

//As well as underscore case handling:
$result['dump_available'];
$result->dump_available;

//You also iterate over the result:
foreach($result as $key=>$value){
   echo "$key:$value";
}

We believe that this provides a more forgiving style of access to the API responses, while still allowing you the flexibility to match your project's style.

If you need to know what values are available for a given API response, please refer to the our developer documentation.

Next, check out more advanced sending options on our Sending Email wiki page, and the other topics listed in the sidebar on the right of this wiki.