mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-09-18 07:26:40 +02:00
62ed1386a3
* fixed typo in Email documentation. * updated link for tutorial code to be relative now that bug #6408 is fixed * removed 2.3 related docs from 2.4 docs folder * fixed typo with Orientation documentation * updated old task url for images/flush
153 lines
4.7 KiB
Markdown
153 lines
4.7 KiB
Markdown
# 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.
|
|
|
|
## 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)).
|
|
|
|
## 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. `<strong>text</strong>` is
|
|
converted to `*text*`).
|
|
|
|
:::php
|
|
$email = new Email($from, $to, $subject, $body);
|
|
$email->send();
|
|
|
|
|
|
The default HTML template is located in `sapphire/templates/email/GenericEmail.ss`.
|
|
|
|
### Sending Plaintext only
|
|
|
|
:::php
|
|
$email = new Email($from, $to, $subject, $body);
|
|
$email->sendPlain();
|
|
|
|
### Custom Template
|
|
|
|
The emails you create may contain quite a bit of content and perhaps custom elements,
|
|
background images and generally be too complex to write out in PHP code.
|
|
|
|
To support this you can specify a [SilverStripe Template](/topics/templates) to be used
|
|
instead of the built in GenericEmail.ss file.
|
|
|
|
* Create a 'MyEmailTemplate.ss' file inside `mysite/templates/email`.
|
|
* Fill MyEmailTemplate.ss with what you need to include. You can use any of the [SilverStripe Template syntax](/topics/templates)
|
|
(e.g. `<% control %>`, `<% if %>`, $FirstName etc). Such as the following:
|
|
|
|
:::ss
|
|
<h1>Hi <% if FirstName %>$FirstName<% end_if %></h1>
|
|
<p>$WelcomeMessage</p>
|
|
|
|
The above is a simple hello email that prints out the first name of the user and
|
|
a welcome message. We're not finished quite yet, there is a couple things we need
|
|
to do:
|
|
|
|
* Before you call `send()` on your email, set the template with `setTemplate()`
|
|
* Populate any custom data into the template with `populateTemplate()` again,
|
|
you need to do this before you call `send()`. In this example above, we used 2
|
|
fields - `$FirstName` and `$WelcomeMessage` so we need to ensure they are populated:
|
|
|
|
:::php
|
|
$email = new Email("from@example.com", "to@example.com", "Welcome to mysite");
|
|
|
|
// sets the template to be used - MyEmail.ss.
|
|
$email->setTemplate('MyEmailTemplate');
|
|
|
|
// You can call populateTemplate multiple times or bundle everything into an array,
|
|
// including DataSetObjects.
|
|
|
|
// Member::currentUser() includes $FirstName
|
|
$email->populateTemplate(Member::currentUser());
|
|
|
|
$welcomeMsg = 'Thank you for joining on '.date('Y-m-d').'!';
|
|
|
|
$email->populateTemplate(array(
|
|
'WelcomeMessage' => $welcomeMsg,
|
|
));
|
|
|
|
$email->send();
|
|
|
|
|
|
|
|
### Subclassing
|
|
|
|
Class definition:
|
|
|
|
:::php
|
|
<?php
|
|
class MyEmail extends Email{
|
|
protected
|
|
$to = '$Email', // Be sure to encase this in single-quotes, as it is evaluated later by the template parser
|
|
$from = 'email@email.com',
|
|
$ss_template = 'MyEmail';
|
|
}
|
|
|
|
Usage:
|
|
|
|
:::php
|
|
$email = new MyEmail();
|
|
$email->send();
|
|
|
|
|
|
### Administrator Emails
|
|
|
|
The static function `Email::setAdminEmail()` can be called from a `_config.php`
|
|
file to set the address that these emails should originate from. This address
|
|
is used if the `from` field is empty.
|
|
|
|
### Redirecting Emails
|
|
|
|
`Email::send_all_emails_to($address)` will redirect all emails sent to the given
|
|
address. We recommend using this in your local development environment. You can
|
|
either configure this in your mysite/_config.php:
|
|
|
|
:::php
|
|
if(Director::isDev()) Email::send_all_emails_to("me@example.com");
|
|
|
|
If you use a [SilverStripe Environment](environment-management) file to manage your
|
|
configuration then you should include the following in your development copy:
|
|
|
|
:::php
|
|
define('SS_SEND_ALL_EMAILS_TO', 'me@example.com');
|
|
|
|
`Email::cc_all_emails_to()` and `Email::bcc_all_emails_to()` will keep the email
|
|
going to its original recipients, but adds an additional recipient in the BCC/CC
|
|
header.
|
|
|
|
:::php
|
|
if(Director::isLive()) Email::bcc_all_emails_to("client@example.com");
|
|
else Email::send_all_emails_to("developer@example.com");
|
|
|
|
|
|
### Setting Custom Headers
|
|
|
|
For email headers which do not have getters or setters (like setTo(), setFrom()) you can use **addCustomHeader($header,
|
|
$value)**
|
|
|
|
:::php
|
|
$email = new Email(...);
|
|
$email->addCustomHeader('HeaderName', 'HeaderValue');
|
|
..
|
|
|
|
|
|
See [Wikipedia E-mail Message header](http://en.wikipedia.org/wiki/E-mail#Message_header) for a list of header names.
|
|
|
|
### Newsletters
|
|
|
|
The [newsletter module](http://silverstripe.org/newsletter-module) provides a UI and logic to send batch emails.
|
|
|
|
## API Documentation
|
|
|
|
`[api:Email]` |