synergitech / postal
FuelPHP library to integrate Postal Email sending
Installs: 6 408
Dependents: 0
Suggesters: 0
Security: 0
Stars: 2
Watchers: 4
Forks: 1
Open Issues: 1
Type:fuel-package
Requires
- composer/installers: ~1.0
- postal/postal: ^1.0
README
FuelPHP-Postal is designed as a fully featured wrapper to the Postal email sending platform.
Currently it handles sending emails, with or without attachments, stores the message ID returned from Postal in a database, and also exposes a webhook receiver to handle notifications from Postal that messages have been delivered, opened etc.
Installation
The recommended way to install fuelphp-postal
is using Composer.
# Install Composer curl -sS https://getcomposer.org/installer | php
Next, run the Composer command to install the latest stable version of fuelphp-postal
.
php composer.phar require synergitech/postal
You will then need database tables for storing the outbound email details and webhook notifications. We have provided FuelPHP migrations to make this easy.
php oil r migrate --packages=postal
Configuration
You need to configure your app to point to your Postal instance and the address from which to send. A basic config looks like this:
return [ 'url' => 'https://yourpostal.io', 'api_key' => 'ABCDEFGHI123456790', 'send-name' => 'Your App Name', 'send-address' => 'noreply@yourapp.io', 'reply-to' => 'reply@yourapp.io', 'template_html' => 'email/generic/html', 'template_text' => 'email/generic/text' ];
The template_text
and template_html
will be used by default as the view files into which your $data
array will be merged using FuelPHP's built in View render()
function.
You will need to add postal
to the config
and package
autoloaders to ensure they are available to your classes.
You can also define an environment variable in your .htaccess
file to send all emails to one address which will help you develop your app.
SetEnv EMAIL you@company.io
You can also achieve this by adding a config value sendallmessagesto
if you would rather not adjust your environment variables.
return [ // ... 'sendallmessagesto' => 'you@company.io' // ... ];
Quick Sending Messages
You can call the send()
function to send an email. Arguments after $to
are optional.
\Synergitech\Postal::send($subject, $body, $to, $to_name, $from, $data, $bcc);
Normal Sending Messages
If you want to access other features such as headers, attachments, and CC, you can forge()
a new object which behaves similarly to Postals PHP library. The $data
and $from
arguments are optional.
$message = \Synergitech\Postal\SendMessage::forge($subject, $body, $data, $from);
Now you can use it to fill in the recipients and send. to()
, cc()
, and bcc()
all function the same way.
$message->to('customer@example.com'); $message->cc('accounts@example.com', 'Accounts Department'); $message->bcc(array( 'tom@example.com' => 'Tom', 'dick@example.com' => 'Dick', 'harry@example.com' => 'Harry' )); $message->attach('report.pdf', 'application/pdf', file_get_contents('report.pdf')); $message->send();
If you want to store your message contents in another view file, send a null body and a 'body_view' item in the $data
array. The view will receive either an $is_text
variable or an $is_html
variable if you need to slightly differentiate between the two.
$message = \Synergitech\Postal\SendMessage::forge($subject, null, ['body_view' => $bodyview] + $data);
Webhooks
You can configure a webhook receiving URL within Postal. You need to create a controller within your FuelPHP project that calls:
\Synergitech\Postal\Webhook::ProcessWebhook();
Example Controller file (be sure to allow unauthenticated requests to pass to this function):
namespace Controller; class Webhook extends \Controller_Rest { public function action_postal() { \Synergitech\Postal\Webhook::ProcessWebhook(); } }
Logging
Using this package means you store a history of email messages and the webhooks let you keep updated with the status of those messages.
To make use of the messages as part of an audit trail, you will be interested in the database objects for the messages you have just sent.
You can set return_email_objects
to true
and any calls to send()
will return an array of database objects which you can do with what you wish.
$sent = $message->send(); $log = \Model\Audit\Log::forge(array( // your specific information here )); $log->save(); foreach ($sent as $email) { \Model\Audit\Item::forge(array( 'log_id' => $log->id, 'email_id' => $email->id ))->save(); }