2014-09-21 02:07:58 +02:00
summary: Send HTML and plain text email from your SilverStripe application.
2011-02-07 07:48:44 +01:00
# Email
2017-07-03 03:22:12 +02:00
Creating and sending email in SilverStripe is done through the [Email ](api:SilverStripe\Control\Email\Email ) and [Mailer ](api:SilverStripe\Control\Email\Mailer ) classes. This document
2016-03-30 02:17:28 +02:00
covers how to create an `Email` instance, customise it with a HTML template, then send it through a custom `Mailer` .
2011-02-07 07:48:44 +01:00
## Configuration
2017-01-13 02:48:46 +01:00
SilverStripe provides an API over the top of the [SwiftMailer ](http://swiftmailer.org/ ) PHP library which comes with an
extensive list of "transports" for sending mail via different services.
Out of the box, SilverStripe will use the built-in PHP `mail()` command via the `Swift_MailTransport` class. If you'd
like to use a more robust transport to send mail you can swap out the transport used by the `Mailer` via config:
```yml
SilverStripe\Core\Injector\Injector:
Swift_Transport: Swift_SendmailTransport
```
2011-02-07 07:48:44 +01:00
## Usage
2014-09-28 10:39:59 +02:00
### Sending plain text only
2011-02-07 07:48:44 +01:00
2017-08-03 02:51:32 +02:00
```php
2011-02-07 07:48:44 +01:00
$email = new Email($from, $to, $subject, $body);
2014-09-28 10:39:59 +02:00
$email->sendPlain();
2017-08-03 02:51:32 +02:00
```
2011-02-07 07:48:44 +01:00
2014-09-28 10:39:59 +02:00
### Sending combined HTML and plain text
2011-02-07 07:48:44 +01:00
2014-09-28 10:39:59 +02:00
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. `<strong>text</strong>` is converted
to `*text*` ).
2011-02-07 07:48:44 +01:00
2017-08-03 02:51:32 +02:00
```php
2011-02-07 07:48:44 +01:00
$email = new Email($from, $to, $subject, $body);
2014-09-28 10:39:59 +02:00
$email->send();
2017-08-03 02:51:32 +02:00
```
2011-02-07 07:48:44 +01:00
2014-09-28 10:39:59 +02:00
< div class = "info" markdown = "1" >
2017-01-13 02:48:46 +01:00
The default HTML template for emails is named `GenericEmail` and is located in `framework/templates/SilverStripe/Email/` .
2017-01-13 17:12:25 +01:00
To customise this template, copy it to the `mysite/templates/Email/` folder or use `setHTMLTemplate` when you create the
2014-09-28 10:39:59 +02:00
`Email` instance.
< / div >
2011-02-07 07:48:44 +01:00
2014-09-28 10:39:59 +02:00
### Templates
2012-12-04 08:00:09 +01:00
2014-09-28 10:39:59 +02:00
HTML emails can use custom templates using the same template language as your website template. You can also pass the
2017-01-13 02:48:46 +01:00
email object additional information using the `setData` and `addData` methods.
2014-09-28 10:39:59 +02:00
**mysite/templates/Email/MyCustomEmail.ss**
2014-09-21 02:07:58 +02:00
2017-08-03 02:51:32 +02:00
```ss
2014-09-28 10:39:59 +02:00
< h1 > Hi $Member.FirstName< / h1 >
< p > You can go to $Link.< / p >
2017-08-03 02:51:32 +02:00
```
2014-09-21 02:07:58 +02:00
2014-09-28 10:39:59 +02:00
The PHP Logic..
2014-09-21 02:07:58 +02:00
2017-01-13 02:48:46 +01:00
```php
$email = SilverStripe\Control\Email\Email::create()
2017-01-13 17:12:25 +01:00
->setHTMLTemplate('Email\\MyCustomEmail')
2017-01-13 02:48:46 +01:00
->setData(array(
2017-05-20 06:32:25 +02:00
'Member' => Security::getCurrentUser(),
2017-01-13 02:48:46 +01:00
'Link'=> $link,
))
->setFrom($from)
->setTo($to)
->setSubject($subject);
if ($email->send()) {
//email sent successfully
} else {
// there may have been 1 or more failures
}
```
2011-02-07 07:48:44 +01:00
2014-09-28 10:39:59 +02:00
< div class = "alert" markdown = "1" >
As we've added a new template file (`MyCustomEmail`) make sure you clear the SilverStripe cache for your changes to
take affect.
< / div >
2011-02-07 07:48:44 +01:00
2017-01-13 17:12:25 +01:00
#### Custom plain templates
By default SilverStripe will generate a plain text representation of the email from the HTML body. However if you'd like
to specify your own own plaintext version/template you can use `$email->setPlainTemplate()` to render a custom view of
the plain email:
```php
2017-07-03 03:22:12 +02:00
$email = new SilverStripe\Control\Email\Email();
2017-01-13 17:12:25 +01:00
$email->setPlainTemplate('MyPlanTemplate');
$this->send();
```
2014-09-28 10:39:59 +02:00
## Administrator Emails
You can set the default sender address of emails through the `Email.admin_email` [configuration setting ](/developer_guides/configuration ).
**mysite/_config/app.yml**
2011-02-07 07:48:44 +01:00
2017-08-03 02:51:32 +02:00
```yaml
2017-01-13 02:48:46 +01:00
SilverStripe\Control\Email\Email:
2014-09-28 10:39:59 +02:00
admin_email: support@silverstripe.org
2017-08-03 02:51:32 +02:00
```
2011-02-07 07:48:44 +01:00
2014-09-28 10:39:59 +02:00
< div class = "alert" markdown = "1" >
Remember, setting a `from` address that doesn't come from your domain (such as the users email) will likely see your
2016-07-08 22:03:30 +02:00
email marked as spam. If you want to send from another address think about using the `setReplyTo` method.
2014-09-28 10:39:59 +02:00
< / div >
2011-02-07 07:48:44 +01:00
2014-09-28 10:39:59 +02:00
## Redirecting Emails
2011-02-07 07:48:44 +01:00
2014-09-28 10:39:59 +02:00
There are several other [configuration settings ](/developer_guides/configuration ) to manipulate the email server.
2011-02-07 07:48:44 +01:00
2017-01-13 02:48:46 +01:00
* `SilverStripe\Control\Email\Email.send_all_emails_to` will redirect all emails sent to the given address.
All recipients will be removed (including CC and BCC addresses). This is useful for testing and staging servers where
you do not wish to send emails out. For debugging the original addresses are added as `X-Original-*` headers on the email.
* `SilverStripe\Control\Email\Email.cc_all_emails_to` and `SilverStripe\Control\Email\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.
2013-03-21 19:48:54 +01:00
2014-09-28 10:39:59 +02:00
Configuration of those properties looks like the following:
**mysite/_config.php**
2011-02-07 07:48:44 +01:00
2017-08-03 02:51:32 +02:00
```php
2014-09-28 10:39:59 +02:00
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");
}
2017-08-03 02:51:32 +02:00
```
2014-09-28 10:39:59 +02:00
2016-07-08 22:03:30 +02:00
### Setting custom "Reply To" email address.
2017-01-13 02:48:46 +01:00
For email messages that should have an email address which is replied to that actually differs from the original "from"
email, do the following. This is encouraged especially when the domain responsible for sending the message isn't
necessarily the same which should be used for return correspondence and should help prevent your message from being
2017-08-03 02:51:32 +02:00
marked as spam.
```php
2011-02-07 07:48:44 +01:00
2014-09-28 10:39:59 +02:00
$email = new Email(..);
2016-07-08 22:03:30 +02:00
$email->setReplyTo('me@address.com');
2017-08-03 02:51:32 +02:00
```
2011-02-07 07:48:44 +01:00
### Setting Custom Headers
2017-01-13 02:48:46 +01:00
For email headers which do not have getters or setters (like setTo(), setFrom()) you can manipulate the underlying
`Swift_Message` that we provide a wrapper for.
2011-02-07 07:48:44 +01:00
2017-08-03 02:51:32 +02:00
```php
2011-02-07 07:48:44 +01:00
$email = new Email(...);
2017-01-13 02:48:46 +01:00
$email->getSwiftMessage()->getHeaders()->addTextHeader('HeaderName', 'HeaderValue');
2011-02-07 07:48:44 +01:00
..
2017-08-03 02:51:32 +02:00
```
2011-02-07 07:48:44 +01:00
2014-09-28 10:39:59 +02:00
< div class = "info" markdown = "1" >
See this [Wikipedia ](http://en.wikipedia.org/wiki/E-mail#Message_header ) entry for a list of header names.
< / div >
2011-02-07 07:48:44 +01:00
2017-01-13 02:48:46 +01:00
## SwiftMailer Documentation
2014-09-25 06:04:56 +02:00
2017-01-13 02:48:46 +01:00
For further information on SwiftMailer, consult their docs: http://swiftmailer.org/docs/introduction.html
2014-09-25 06:04:56 +02:00
2011-02-07 07:48:44 +01:00
## API Documentation
2017-07-03 03:22:12 +02:00
* [Email ](api:SilverStripe\Control\Email\Email )