Sending email is an important part of almost any web software available today. Social Suite applications have varying needs for sending email. Examples include allowing users to confirm their email address during registration, advising users when there are updates regarding content they are following, and bulk mailing your member base to alert them to something important regarding your site. While functionally the email handler has not significantly changed in 4.0, the process has been vastly simplified, allowing you to send more consistent emails with far less code than in the past.
Building and sending emails
When sending email in the Social Suite, there are two primary types of email you might need to send: an email based on a pre-existing template that you swap out variables in, and a completely custom email where you define the body specifically for the current email being sent. Both of these scenarios are accounted for. First, let's take a look at the simpler and more common scenario where you send an email based on a template.
IPSEmail::buildFromTemplate( 'core', 'admin_spammer', array( $this ) )->send( IPSSettings::i()->email_in );
Here, we are building an email from a template ("admin_spammer" in the "core" application, more on that in a moment), passing the current object in for purposes of replacing out variables in the template, and then calling the send method to actually send the email, passing the recipient to it. The buildFromTemplate() method is a factory method that will create a new object of type IPSEmail. When calling the send() method, you can optionally pass a single email address to send the email too, an array of email addresses to send the email to, or a single instance of IPSMember or an array of IPSMember instances to send the email to. The library takes care of the rest.
The other type of email you may need to send is a completely custom email where you define the entire body without using a template. Bulk mails are a good example of this type of email. You can easily send these types of emails as well.
$email = IPSEmail::buildFromContent( $subject, $htmlBody, $plaintextBody ); $email->from = "john@doe.com"; $email->send( "jane@doe.com" );
Here we call the factory method buildFromContent(), passing in the email subject, the HTML email body, and the plain text email body. You can optionally omit the plain text email body and it will be generated for you automatically.
We then specify the from address (which defaults to the suite's outgoing email address), and finally we call the send() method, passing in an email address.
While it is not recommended, you can create an email object without specifying either email body parameter, and specify these later if you have a need.
Further control and options
Beyond what is outlined above, you have fine-grain control over the details of the email being sent. The following example outlines more of the possible values you can specify when necessary
$email = IPSEmail::buildFromContent( "Hello world" ); $email->from = "john@doe.com"; $email->fromName = "John Doe"; $email->subject = "Changed my mind to hello planet"; $email->useWrapper = FALSE; $email->headers['X-Mailer'] = "My cool app"; $email->headers['Priority'] = 3; $email->setBody( array( 'html' => "<html><body><b>My email</b></body></html>", 'plain' => "My email" ) ); $email->send( array( "jane@doe.com", "janet@doe.com" ), array( "abc@abc.com" ), array( "test@test.com" ) );
Most of the above should be self-explanatory. Just a few quick notes:
- You can set the $useWrapper property to FALSE if you do not wish for the email to be wrapped in the standard default HTML and plaintext email wrappers. The wrappers primarily define the HTML structure (doctype, html tag, etc.) and also allow for automatic definition of the unsubscribe link.
- You can call the $unsubscribe property to manually define an unsubscribe link and the text to display. Alternatively, you can call the "buildUnsubscribe()" method (see below) to do this automatically and consistently. There is no point in doing this if you do not use the wrapper, however, which is why it is omitted in the example above (in this case you should manually include an unsubscribe link if appropriate).
- The first parameter passed to the send() method is the to addresses. The second is the CC addresses, and the third is the BCC addresses, if necessary.
Automatically handling an unsubscribe link
Links to handle unsubscribing from emails can be accommodated automatically with emails sent through the email handler. For bulk emails, the following method is called
$email->buildUnsubscribe( 'bulk', IPSMember::loggedIn() );
The first parameter is the 'type', which is 'bulk' in this case. The second parameter when specifying an unsubscribe link for a bulk email should be the member who is being emailed, as their personal details are used to generate a unique key allowing one-click unsubscribing.
When sending notification emails, you still call buildUnsubscribe() with the following parameters
$email->buildUnsubscribe( 'notification', 'my_notification_key' );
Instead of a one-click unsubscribe link being included, a link pointing to the user's notification preferences area will be included instead, highlighting the notification preference that caused the email to be sent.
Unsubscribe links are only automatically included in the outgoing email if you (1) call this method, and (2) use the default wrappers.
Email templates
While we will touch on this further in a future blog entry, email templates are now defined in a similar manner to HTML templates, and there is one template for the HTML version of the email and one template for the plaintext version of the email. This allows us to better tailor the email being sent dependent upon the content-type in order to provide the nicest experience for the user. The email subject is a language string based upon the email template name and is determined automatically by the email library when buildFromTemplate() is called.
Wrapping Up
While the email library still provides plenty of control to accomodate almost any scenario encountered within the Social Suite, for day to day needs the interface to send emails has been vastly simplified in order to provide a more consistent experience for both the user and the developers integrating applications within the Suite. We hope you find these small changes will make your jobs easier, without losing the control you have presently.
