znarkus / postmark-php

Postmark PHP class

Postmark PHP class

Copyright 2009 - 2011, Markus Hedlund, Mimmin AB, www.mimmin.com Licensed under the MIT License. Redistributions of files must retain the above copyright notice.

Additional contributors

• Jeff Downie
• August Trometer
• Hristo Deshev
• jeffreyhunter77
• John Beales
• Geoff Wagstaff
• beaudesigns
• Gabriel Bull

Requirements

All in-data must be encoded with UTF-8.

Getting started

// Create a "server" in your "rack", then copy it's API key
$postmarkApiKey = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
    
// Create a message and send it
Postmark\Mail::compose($postmarkApiKey)
    ->from('[email protected]', 'John Smith')
    ->addTo('[email protected]', 'Jane Smith')
    ->subject('Subject')
    ->messagePlain('Plaintext message')
    ->send();

Configuration

There are two ways of configuration.

Adapter

An adapter class should be used for a more dynamic configuration. The adapter must implement Postmark\MailAdapterInterface. These are the methods that must be implemented.

• getApiKey - Should return the API key
• setupDefaults(Postmark\Mail &$mail) - May be used to setup a default email, e.g. set From address.
• log($logData) - Is called immediately after the email is sent. $logdata is an array with keys messageData, return, curlError and httpCode.

See Tests/Adapter.php for example usage.

Usage

Postmark\Mail::compose($postmarkApiKey)
	->from('[email protected]', 'Name')
	->addTo('[email protected]', 'Name')
	->subject('Subject')
	->messagePlain('Plaintext message')
	->send();

or:

$email = new Postmark\Mail($postmarkApiKey);
$email->from('[email protected]', 'Name')
	->addTo('[email protected]', 'Name')
	->subject('Subject')
	->messagePlain('Plaintext message')
	->send();

Error handling

See PHPDOC for details on Exceptions thrown. If no API key is set, an E_USER_ERROR will be raised.

Debugging

Call method debug(Postmark\Mail::DEBUG_VERBOSE) or debug(Postmark\Mail::DEBUG_RETURN) to enable debug mode. DEBUG_VERBOSE prints debug info and DEBUG_RETURN makes send() return debug info as an array.

Unit tests

Unit tests are located in Tests/. Simple test is the unit test framework being used.

Adapter.php runs all tests relevant for adapter configuration.

E-mail address validation

This class uses a regular expression to validate e-mail addresses, in addition to the validation Postmark does. This regex isn't perfect. If you need more extensive validation, please try http://www.dominicsayers.com/isemail/.

postmark-php's Issues

update validation to allow sending "Bcc" and "Cc" without "To"

Postmark now allows the sending of "Bcc" and "Cc" but the postmark-php validation forces a "To" address to be set.

Email Validation is in error

Hi, I noticed you updated your RegEx to validate emails, but the one you use fails on some basic legitimate email addresses such as "hellothere"@example.com - I would recommend using the library available from http://www.dominicsayers.com/isemail/ for the most comprehensive/correct email validation

Can we make releases?

Or add me on the project team so I can make them.

Change API key on existing instance

I think, it would be useful to have an option to change the API key on an existing instance. We are using your class within a batch job and need to change "Servers" back and forth, depending on the message we are currently processing. For now, we have just added these few lines:

/**
* Set or change the Postmark API key
*
* @param string $apiKey Postmark API key
* @return Mail_Postmark
*/
public function &setApiKey($apiKey)
{
  $this->_apiKey = $apiKey;
  return $this;
}

Support for multiple 'To' addresses?

The Postmark API Documentation says, in reference to the 'To' field:

You can pass multiple recipient addresses in the ‘To’ field and the optional ‘Cc’ and ‘Bcc’ fields. Separate multiple addresses with a comma. Note that Postmark has a limit of twenty recipients per message in total. You need to take care not to exceed that limit. Otherwise you will get an error.

It seems like Postmark.php (and, by association, the Postmark Drupal Module), only supports a single 'To' address.

If I set the 'To' address with:

$email->to('[email protected],[email protected]');

an exception is thrown:

Fatal error: Uncaught exception 'Exception' with message 'Invalid to address ''[email protected],[email protected]'' in Postmark.php:230

Support for batch sending

Would love to see support for batch sending. Do you have this planned already?

Optionally use http instead of https

Would it be possible to have a constant to say whether or not to use http or https?

email validation function _validateAddress now fails on new style tlds

Big fat warning for anyone still making use of this or considering using it.

The email validation function _validateAddress has a specific length check for the final part tld of the domain. It's limited to 6 characters.

Enter such domains as .academy (7 characters) and watch the invalid email exceptions fly.

Suppress InvalidArgumentException Fatal Error in DEBUG_RETURN Mode

When an email address is invalid a fatal InvalidArgumentException error is thrown (line 443). This behaviour is expected when using debug(Mail_Postmark::DEBUG_VERBOSE) not but when using debug(Mail_Postmark::DEBUG_RETURN).

I would suggest that when using debug(Mail_Postmark::DEBUG_RETURN) the error should be returned as an array not output as a fatal error.

Add ability to clear "to" addresses

It would be useful to have a method named clearRecipients() or something that would allow for the recipients (to, cc, bcc) to be cleared out. That way a single instance of the postmark class could be reused to send an email to a few people without them all being in the same email.

Email Validation

The email validation is does not validate for .name TLDs

Fix class_exists() to work with autoloaders

You should add a second parameter to this code:

if (class_exists('Mail_Postmark_Adapter'))

so that is becomes:

if (class_exists('Mail_Postmark_Adapter', false))

Otherwise, if you use the Postmark class in your project that already supports __autoload() function, it will try to find this class on his own and will most ceirtanly fail (at least in Zend Framework which looks up PHP classes based on their names).

Any chance you'll be upgrading the lib to support batch emailing?

Any chance you'll be upgrading the lib to support batch emailing?
http://developer.postmarkapp.com/developer-send-api.html
See bottom "Send batch emails"

Not clearing the email data anywhere in postmark.php

Not clearing the email data anywhere in postmark.php. Need a method to clear all email data like 'ClearAddresses()' in phpmailer class

Header Content-Type forced to "application/json"

It would be nice if we could set the header Content-Type to something other than application/json. Currently I'm trying to send calendar invites and I would like to be able to set Content-Type to text/calendar but I get the error "Header 'Content-Type' not allowed".

SSL no longer needed - causes problems with PM - MailPHP

Remove this:

---

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);

prev | curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
prev | curl_setopt($ch, CURLOPT_CAINFO, dirname(FILE) . '/Certificate/cacert.pem');

Inline images in html messages

I can't seem to find how to set the content id for an attachment to pass an inline image through Postmark.