Sending Emails

Overview

Seagull provides the class SGL_Emailer for sending emails. It's a wrapper around PEAR::mail so there are quite a few options available.

In the modules provided with Seagull there are a number of examples and variations of sending email with SGL_Emailer.

Example

Sending an HTML email:

    $options = array(
        'toEmail'       => $conf['email']['info'],
        'toRealName'    => 'Admin',
        'fromEmail'     => $oContact->email,
        'fromRealName'  => $contacterName,
        'replyTo'       => $oContact->email,
        'subject'       => 'Contact Enquiry from ' . $conf['site']['name'],
        'type'          => $oContact->type,
        'body'          => $oContact->comment,
        'template'      => SGL_MOD_DIR . '/' . $this->module . '/templates/' .
            $_SESSION['prefs']['theme'] . '/email_contact_us.php',
    );
    $message = & new SGL_Emailer($options);
    $message->prepare();
    return $message->send();

Adding multiple attachments to a single email

  • requires >= Seagull 0.6.3

You can add multiple attachments to a single email. When passing the $options 'filepath' parameter as an array, each entry in the array will be added as a separate attachment. When the $options parameter 'mimetype' gets passed as an array containing the same number of values as 'filepath', each attachment gets a unique mimetype, otherwise the same mimetype for all attachments is used.

In this example two attachments have their own mimetype:

 $options = array(
      ...
      'filepath'      => array('path/to/gif','path/to/jpg'),
      'mimetype'      => array('image/gif','image/jpeg'),
 );  

In this example all attachments get the same mimetype:

 $options = array(
     ...
     'filepath'      => array('path/to/file1','path/to/file2'),
     'mimetype'      => 'text/plain',
 );

Using improved functionality available in SGL_Emailer2

  • requires >= Seagull 0.6.5

With SGL_Emailer2 you can send text AND html emails in a single call, or you can have your HTML emails automatically converted to text. The conversion will happen if you have Horde's Text_Filter lib installed, which can be obtained here:

$ pear channel-discover pear.horde.org
$ pear install horde/horde_text_filter

Example

PHP code

        ...
        // delivery options
        $aDeliveryOpts['toEmail']  = 'your data here';
        $aDeliveryOpts['toRealName'] = 'your data here';
        ...
        $aDeliveryOpts['fromEmail'] = 'your data here';.
        $aDeliveryOpts['fromRealName']  = 'your data here';
        // template vars
        $aTplOpts['var1'] = 'val1';
        $aTplOpts['var2'] = 'val2';
        $aTplOpts['var3'] = 'val3';
        // obligatory template options
        $aTplOpts['moduleName']    = 'mymodule';
        $aTplOpts['htmlTemplate']  = 'mytemplate.html';
        $aTplOpts['textTemplate'] = 'mytemplate.txt';
        // optionally send emails to queue for later sending
        $aQueueOpts['sendDelay'] = 'your send delay';.
        $aQueueOpts['groupId']  = 'your group';
        $aQueueOpts['userId']  = 'your user ID';
        $aQueueOpts['batchId']  = 'your batch ID';
        $ok = SGL_Emailer2::send($aDeliveryOpts, $aTplOpts, $aQueueOpts);

HTML template

...
<p>
    Var1: {var1}<br />
    Var2: {var2}<br />
    Var3: {var3}<br />
</p>
<p>
    Bye!
</p>
...

Text template

...
$bodyTxt = <<< TXT
    ...
    Var1: {$aParams['var1']}
    Var2: {$aParams['var2']}
    Var3: {$aParams['var3']}
    Bye!
    ...
TXT;
...

More info

  • if you want to specify the email format use the relevant class constants, MODE_TEXT_ONLY or MODE_HTML_ONLY or MODE_HTML_AND_TEXT, eg:
    $aTplOpts['mode'] = SGL_Emailer_Builder::MODE_HTML_ONLY;
    
  • if you choose MODE_HTML_AND_TEXT and don't supply a text template, SGL_Emailer2 will create a text version of your email by converting the HTML content to text
  • if you want to send a large number of emails (>1000) you may want to install the email queue module which is available in the default distribution of Seagull. This module let's you send emails offline, and you can specify things like intervals between sending, number of attempts per email, batch IDs and custom backends, the default being DB.
  • SGL_Emailer2 also allows you to pass custom emailqueue params that will override the defaults, eg
     possible keys:
      * sendDelay
      * groupId
      * userId
      * batchId
    

This is sent as the optional 3rd arg to SGL_Emailer2::send, ie

$ok = SGL_Emailer2::send($aDeliveryOpts, $aTplOpts, $aQueueOpts);

You will also need to enable email queuing before you call Emailer2

$set = SGL_Config::set('emailQueue.enabled', true);