Introduction  

The mailing module supports adding your own custom mail transport via events available through the mailing module.

Implementation  

The mailing module triggers events to allow for custom modules to provide their own mail providers. This can be a third party mailing provider (sendgrid, mailchimp, etc) or any other custom mailing service. To implement a custom mail transport, you have to hook into the events triggered by the mailing module (to read more about events, see the Events documentation). Your custom mail transport will have to take care of rendering a configuration section in the mailing module's mailing configuration, transferring the messages to the users, and communicate back if messages are sent or failed.

Hooking into the events  

To integrate your own mail transport, you have to hook into four events for four different purposes:

Providing the mailing module with a list of custom transports  

When showing the list of available mail transports in the mailing module (default is "php" and "custom"), the mailing module triggers an event that you can listen to and add your transport to the event's return list.

// Mailing module event
$event = TBGEvent::createNew('mailing', 'list_mailproviders');
$event->trigger();
$this->providers = $event->getReturnList();
	
// Example integration function
function listenMailingListMailProviders(TBGEvent $event)
{
	$event->addToReturnList("My mail transport", "mymailtransport");
}

The mailing module will then use the return list to build the list of transports, using the return list key as the identifier (stored in the backend) and the description provided as the description in the configuration interface.

Providing a configuration interface for your mail transport  

You have to provide a template for configuring your mail transport. This template will be rendered in the mailing module's configuration section when choosing your custom transport as the selected method of sending emails.

<?php TBGEvent::createNew('mailing', 'settings_provider_config')->trigger(); ?>

Your configuration template container must have the id "mail_type_mymailtransport_info" (where "mymailtransport" matches the key above) and the class mail_config, and must take care of its own initial shown or hidden state (example below):

// Put this in the container's "style" property, where "mymailtransport" matches the key provided above:
<?php if (TBGContext::getModule('mailing')->getMailerType() != "mymailtransport"): ?> display: none;<?php endif; ?>

This template will be posted to the module's configuration save method, where a save event will be triggered. See the next section for examples.

Saving settings from the configuration template  

The mailing module triggers an event for saving the configuration details of your custom mail transport:

$event = TBGEvent::createNew('mailing', 'TBGMailing::postConfigSettings', null, compact($request));
$event->trigger();

if (!$event->isProcessed()) { // ... }

If you take care of saving all the details, mark the events as processed. If you want to pass on saving the non-custom parameters to the mailing module, don't mark the event as processed, and the mailing module will take care of saving the rest of the configuration details.

function listenTBGMailing_postConfigSettings(TBGEvent $event)
{
	$request = $event['request'];
	$mymodule->saveSetting($request['mysetting']);

	// If you don't want the mailing module to save anything, mark the event as processed
	$event->setProcessed();

	// If you want to hand off saving the rest of the configuration details to the mailing module, just don't mark it as processed
	// You should not mark it as "not processed", since there might be *other* modules overriding yours.
}

Sending messages  

When sending messages, the mailing module will hand messages off to your module if it is marked as the selected mail transport. This is done either "live", or (if using the mail queue) when the cli task is processed. In both cases, you get a !TBGMimemail object which you must process.

"Live"  

The live method will just hand the !TBGMimemail object about to be sent off to you, and then just throw the object away when your event is done with it, completely bypassing the builtin mailing methods. You must take care of handling the sending of the message yourself, and all the contents of the email is in the !TBGMimemail object.

// Mailing module event, where $mail is a TBGMimemail object
TBGEvent::createNew('mailing', 'TBGMailing::sendMail', $mail)->trigger();

// Example event handler
function listenTBGMailing_sendMail(TBGEvent $event)
{
	$message = $event->getSubject();
	// Do something with the message
}

Queuing  

The cli task will hand you all emails that have currently been selected for sending, and expects two items in the event's return list: a list of message ids that can be removed from the queue, and the number of failed items.

// Mailing module event, where $mail is a TBGMimemail object
$event = TBGEvent::createNew('mailing', 'CliMailingProcessMailQueue::sendMail', $mailing, array('messages' => $messages));
$event->trigger();
$processed_messages = $event->getReturnListValue('processed_messages');
$failed_messages = $event->getReturnListValue('failed_messages');

// Example event handler
function listenCliMailingProcessMailQueue_sendMail(TBGEvent $event)
{
	$messages = $event['messages'];
	// Do something with the messages

	$event->addToReturnList(array_keys($messages), 'processed_messages');
	$event->addToReturnList(0, 'failed_messages');
}