From 720ff48d2890a9f14f35eb1986d5671989962249 Mon Sep 17 00:00:00 2001 From: Will Rossiter Date: Sun, 28 Sep 2014 21:39:59 +1300 Subject: [PATCH] Review email documentation --- docs/en/02_Developer_Guides/10_Email/index.md | 218 +++++++++++++----- 1 file changed, 156 insertions(+), 62 deletions(-) diff --git a/docs/en/02_Developer_Guides/10_Email/index.md b/docs/en/02_Developer_Guides/10_Email/index.md index 062a24566..e640f16d9 100644 --- a/docs/en/02_Developer_Guides/10_Email/index.md +++ b/docs/en/02_Developer_Guides/10_Email/index.md @@ -2,104 +2,153 @@ summary: Send HTML and plain text email from your SilverStripe application. # Email -SilverStripe has emailing functionality using the built-in mail() function in PHP. -Features include sending plaintext- and HTML emails, sending bulk emails, subscription, handling bounced back emails. +Creating and sending email in SilverStripe is done through the [api:Email] and [api:Mailer] classes. This document +covers how to create an `Email` instance, customize it with a HTML template, then send it through a custom `Mailer`. ## Configuration -Your PHP configuration needs to include the SMTP module for sending emails. -If you are not running an SMTP server together with your webserver, you might need to setup PHP with the credentials for -an external SMTP server (see [PHP documentation for mail()](http://php.net/mail)). +Out of the box, SilverStripe will use the built-in PHP `mail()` command. If you are not running an SMTP server, you +will need to either configure PHP's SMTP settings (see [PHP documentation](http://php.net/mail) to include your mail +server configuration or use one of the third party SMTP services like [Mandrill](https://github.com/lekoala/silverstripe-mandrill) +and [Postmark](https://github.com/fullscreeninteractive/silverstripe-postmarkmailer). ## Usage -### Sending combined HTML and Plaintext - -By default, emails are sent in both HTML and Plaintext format. -A plaintext representation is automatically generated from the system -by stripping HTML markup, or transforming it where possible -(e.g. `text` is converted to `*text*`). - - :::php - $email = new Email($from, $to, $subject, $body); - $email->send(); - - -The default HTML template is located in `framework/templates/email/GenericEmail.ss`. - -### Sending Plaintext only +### Sending plain text only :::php $email = new Email($from, $to, $subject, $body); $email->sendPlain(); -### Templates +### Sending combined HTML and plain text -* Create a SS-template file called, in this example we will use 'MyEmail.ss' inside `mysite/templates/email`. -* Fill this out with the body text for your email. You can use any [SS-template syntax](/topics/templates) (e.g. `<% loop %>`, -`<% if %>`, $FirstName etc) -* Choose your template with **setTemplate()** -* Populate any custom data into the template before sending with **populateTemplate()** - -Example: +By default, emails are sent in both HTML and Plaintext format. A plaintext representation is automatically generated +from the system by stripping HTML markup, or transforming it where possible (e.g. `text` is converted +to `*text*`). :::php $email = new Email($from, $to, $subject, $body); - $email->setTemplate('MyEmail'); + $email->send(); - // You can call this multiple times or bundle everything into an array, including DataSetObjects - $email->populateTemplate(Member::currentUser()); +
+The default HTML template for emails is named `GenericEmail` and is located in `framework/templates/email/`. To +customize this template, copy it to the `mysite/templates/Email/` folder or use `setTemplate` when you create the +`Email` instance. +
- $welcomeMsg = 'Thank you for joining on '.date('Y-m-d'.'!'); - $email->populateTemplate(array( - 'WelcomeMessage' => $welcomeMsg, // Accessible in template via $WelcomeMessage - )); +### Templates + +HTML emails can use custom templates using the same template language as your website template. You can also pass the +email object additional information using the `populateTemplate` method. + +**mysite/templates/Email/MyCustomEmail.ss** + + :::ss +

Hi $Member.FirstName

+

You can go to $Link.

+ +The PHP Logic.. + + :::php + $email = new Email(); + $email + ->setFrom($from) + ->setTo($to) + ->setSubject($subject) + ->setTemplate('MyCustomEmail') + ->populateTemplate(new ArrayData(array( + 'Member' => Member::currentUser(), + 'Link' => $link + ))); $email->send(); +
+As we've added a new template file (`MyCustomEmail`) make sure you clear the SilverStripe cache for your changes to +take affect. +
-### Subclassing +## Sub classing -Class definition: +To keep your application code clean and your internal API clear, a better approach to generating an email is to create +a new subclass of `Email` which takes the required dependencies and handles setting the properties itself. + +**mysite/code/MyCustomEmail.php** :::php Email; + $subject = "Welcome to our site."; + $link = Director::absoluteBaseUrl(); + + parent::__construct($from, $to, $subject); + + $this->populateTemplate(new ArrayData(array( + 'Member' => $member->Email, + 'Link' => $link + ))); + } } - -Usage: +Then within your application, usage of the email is much clearer to follow. :::php populateTemplate(Member::currentUser()); // This will populate the template, $to, $from etc variables if they exist - $email->send(); // Will immediately send an HTML email with appropriate plain-text content + $member = Member::currentUser(); + + $email = new MyEmail($member); + $email->send(); -### Administrator Emails +## Administrator Emails -You can influence the default sender address of emails through the `Email.admin_email` -[configuration setting](/topics/configuration). This address is used if the `from` field is empty. +You can set the default sender address of emails through the `Email.admin_email` [configuration setting](/developer_guides/configuration). -### Redirecting Emails +**mysite/_config/app.yml** -Further [configuration settings](/topics/configuration) relating to email rewriting: + :::yaml + Email: + admin_email: support@silverstripe.org + -* `Email.send_all_emails_to` will redirect all emails sent to the given address. Handy for testing! -* `Email.cc_all_emails_to` and `Email.bcc_all_emails_to` will keep the email going to its original recipients, but -add an additional recipient in the BCC/CC header. Good for monitoring system-generated correspondence on the live -systems. +
+Remember, setting a `from` address that doesn't come from your domain (such as the users email) will likely see your +email marked as spam. If you want to send from another address think about using the `replyTo` method. +
+ +## Redirecting Emails + +There are several other [configuration settings](/developer_guides/configuration) to manipulate the email server. + +* `Email.send_all_emails_to` will redirect all emails sent to the given address. This is useful for testing and staging +servers where you do not wish to send emails out. +* `Email.cc_all_emails_to` and `Email.bcc_all_emails_to` will add an additional recipient in the BCC / CC header. +These are good for monitoring system-generated correspondence on the live systems. + +Configuration of those properties looks like the following: + +**mysite/_config.php** :::php - if(Director::isLive()) Config::inst()->update('Email', 'bcc_all_emails_to', "client@example.com"); - else Config::inst()->update('Email', 'send_all_emails_to', "developer@example.com"); + if(Director::isLive()) { + Config::inst()->update('Email', 'bcc_all_emails_to', "client@example.com"); + } else { + Config::inst()->update('Email', 'send_all_emails_to', "developer@example.com"); + } +### Setting custom replyTo + + :::php + $email = new Email(..); + $email->replyTo('me@address.com'); ### Setting Custom Headers @@ -111,13 +160,58 @@ $value)** $email->addCustomHeader('HeaderName', 'HeaderValue'); .. +
+See this [Wikipedia](http://en.wikipedia.org/wiki/E-mail#Message_header) entry for a list of header names. +
-See [Wikipedia E-mail Message header](http://en.wikipedia.org/wiki/E-mail#Message_header) for a list of header names. - -### Newsletters +## Newsletters The [newsletter module](http://silverstripe.org/newsletter-module) provides a UI and logic to send batch emails. +## Custom Mailers + +SilverStripe supports changing out the underlying web server SMTP mailer service through the `Email::set_mailer()` +function. A `Mailer` subclass will commonly override the `sendPlain` and `sendHTML` methods to send emails through curl +or some other process that isn't the built in `mail()` command. + +
+There are a number of custom mailer add-ons available like [Mandrill](https://github.com/lekoala/silverstripe-mandrill) +and [Postmark](https://github.com/fullscreeninteractive/silverstripe-postmarkmailer). +
+ +In this example, `LocalMailer` will take any email's going while the site is in Development mode and save it to the +assets folder instead. + +**mysite/code/LocalMailer.php** + + :::php +