Version: current

# Class Email

Class to support sending emails.

  Object
  ViewableData implements IteratorAggregate
  Email

### Direct known subclasses

`Member_ChangePasswordEmail`, `Member_ForgotPasswordEmail`, `Member_SignupEmail`, `Newsletter_Email`, `SimpleOrderPage_SubmittedFormEmail`, `UserDefinedForm_SubmittedFormEmail`

Package: sapphire\email
Located at sapphire/email/Email.php

## Methods summary

`public static` | # `set_mailer( `Mailer` $mailer )` This can be used to provide a mailer class other than the default, e.g. for testing. This can be used to provide a mailer class other than the default, e.g. for testing. #### Parameters $mailer Mailer $mailer
`public static `Mailer`` | # `mailer( )` Get the mailer. Get the mailer. #### Returns ``Mailer`` Mailer
`public` | # `__construct( mixed $from = null, mixed $to = null, mixed $subject = null, mixed $body = null, mixed $bounceHandlerURL = null, mixed $cc = null, mixed $bcc = null )` Create a new email. Create a new email. #### Overrides `Object::__construct`
`public` | # `attachFileFromString( mixed $data, mixed $filename, mixed $mimetype = null )`
`public` | # `setBounceHandlerURL( mixed $bounceHandlerURL )`
`public` | # `attachFile( mixed $filename, mixed $attachedFilename = null, mixed $mimetype = null )`
`public` | # `Subject( )`
`public` | # `Body( )`
`public` | # `To( )`
`public` | # `From( )`
`public` | # `Cc( )`
`public` | # `Bcc( )`
`public` | # `setSubject( mixed $val )`
`public` | # `setBody( mixed $val )`
`public` | # `setPlainBody( mixed $val )`
`public` | # `setTo( mixed $val )`
`public` | # `setFrom( mixed $val )`
`public` | # `setCc( mixed $val )`
`public` | # `setBcc( mixed $val )`
`public` | # `replyTo( string $email )` Set the "Reply-To" header with an email address. Set the "Reply-To" header with an email address. #### Parameters $email string $email The email address of the "Reply-To" header
`public` | # `addCustomHeader( string $headerName, string $headerValue )` Add a custom header to this value. Useful for implementing all those cool features that we didn't think of. Add a custom header to this value. Useful for implementing all those cool features that we didn't think of. #### Parameters $headerName string $headerName $headerValue string $headerValue
`public` | # `BaseURL( )`
`public` | # `debug( )` Debugging help Debugging help
`public` | # `setTemplate( string $template )` Set template name (without *.ss extension). Set template name (without *.ss extension). #### Parameters $template string $template
`public string` | # `getTemplate( )` #### Returns `string` string
`protected` | # `templateData( )`
`public` | # `IsEmail( )` Used by `SSViewer` templates to detect if we're rendering an email template rather than a page template Used by `SSViewer` templates to detect if we're rendering an email template rather than a page template
`public` | # `populateTemplate( mixed $data )` Populate this email template with values. This may be called many times. Populate this email template with values. This may be called many times.
`protected` | # `parseVariables( mixed $isPlain = false )` Load all the template variables into the internal variables, including the template into body. Called before send() or debugSend() $isPlain=true will cause the template to be ignored, otherwise the GenericEmail template will be used and it won't be plain email :) Load all the template variables into the internal variables, including the template into body. Called before send() or debugSend() $isPlain=true will cause the template to be ignored, otherwise the GenericEmail template will be used and it won't be plain email :)
`public string` | # `renderWith( string|array|`SSViewer` $template, array $customFields = null )` Render this object into the template, and get the result as a string. You can pass one of the following as the $template parameter: - a template name (e.g. Page) - an array of possible template names - the first valid one will be used - an SSViewer instance Render this object into the template, and get the result as a string. You can pass one of the following as the $template parameter: - a template name (e.g. Page) - an array of possible template names - the first valid one will be used - an SSViewer instance #### Parameters $template string|array|SSViewer $template the template to render into $customFields array $customFields fields to customise() the object with before rendering #### Returns `string` string #### Overrides `ViewableData::renderWith`
`public static` | # `validEmailAddress( mixed $address )` #### Desc Validates the email address. Returns true of false
`public boolean` | # `sendPlain( string $messageID = null )` Send the email in plaintext. Send the email in plaintext. #### Parameters $messageID string $messageID Optional message ID so the message can be identified in bounces etc. #### Returns `boolean` Success of the sending operation from an MTA perspective. Doesn't actually give any indication if the mail has been delivered to the recipient properly) #### See send() for sending emails with HTML content. #### Uses ``Mailer::sendPlain()``
`public boolean` | # `send( string $messageID = null )` Send an email with HTML content. Send an email with HTML content. #### Parameters $messageID string $messageID Optional message ID so the message can be identified in bounces etc. #### Returns `boolean` Success of the sending operation from an MTA perspective. Doesn't actually give any indication if the mail has been delivered to the recipient properly) #### See sendPlain() for sending plaintext emails only. #### Uses ``Mailer::sendHTML()``
`public static` | # `setAdminEmail( string $newEmail )` Used as a default sender address in the `Email` class unless overwritten. Also shown to users on live environments as a contact address on system error pages. Used as a default sender address in the `Email` class unless overwritten. Also shown to users on live environments as a contact address on system error pages. Used by Email->send(), Email->sendPlain(), Debug->friendlyError(). #### Parameters $newEmail string $newEmail
`public static string` | # `getAdminEmail( )` #### Returns `string` string
`public static` | # `send_all_emails_to( mixed $emailAddress )` Send every email generated by the Email class to the given address. It will also add " [addressed to (email), cc to (email), bcc to (email)]" to the end of the subject line This can be used when testing, by putting a command like this in your _config.php file Send every email generated by the Email class to the given address. It will also add " [addressed to (email), cc to (email), bcc to (email)]" to the end of the subject line This can be used when testing, by putting a command like this in your _config.php file if(!Director::isLive()) Email::send_all_emails_to("someone@example.com")
`public static` | # `cc_all_emails_to( mixed $emailAddress )` CC every email generated by the Email class to the given address. It won't affect the original delivery in the same way that send_all_emails_to does. It just adds a CC header with the given email address. Note that you can only call this once - subsequent calls will overwrite the configuration variable. CC every email generated by the Email class to the given address. It won't affect the original delivery in the same way that send_all_emails_to does. It just adds a CC header with the given email address. Note that you can only call this once - subsequent calls will overwrite the configuration variable. This can be used when you have a system that relies heavily on email and you want someone to be checking all correspondence. if(Director::isLive()) Email::cc_all_emails_to("supportperson@example.com")
`public static` | # `bcc_all_emails_to( mixed $emailAddress )` BCC every email generated by the Email class to the given address. It won't affect the original delivery in the same way that send_all_emails_to does. It just adds a BCC header with the given email address. Note that you can only call this once - subsequent calls will overwrite the configuration variable. BCC every email generated by the Email class to the given address. It won't affect the original delivery in the same way that send_all_emails_to does. It just adds a BCC header with the given email address. Note that you can only call this once - subsequent calls will overwrite the configuration variable. This can be used when you have a system that relies heavily on email and you want someone to be checking all correspondence. if(Director::isLive()) Email::cc_all_emails_to("supportperson@example.com")
`public boolean` | # `is_valid_address( string $email )` Checks for RFC822-valid email format. Checks for RFC822-valid email format. #### Parameters $email string $str #### Returns `boolean` boolean #### Copyright Cal Henderson <cal@iamcal.com> This code is licensed under a Creative Commons Attribution-ShareAlike 2.5 License http://creativecommons.org/licenses/by-sa/2.5/ #### See http://code.iamcal.com/php/rfc822/rfc822.phps
`public static string` | # `obfuscate( string $email, string $method = 'visible' )` Encode an email-address to protect it from spambots. At the moment only simple string substitutions, which are not 100% safe from email harvesting. Encode an email-address to protect it from spambots. At the moment only simple string substitutions, which are not 100% safe from email harvesting. #### Parameters $email string $email Email-address $method string $method Method for obfuscating/encoding the address - 'direction': Reverse the text and then use CSS to put the text direction back to normal - 'visible': Simple string substitution ('@' to '[at]', '.' to '[dot], '-' to [dash]) - 'hex': Hexadecimal URL-Encoding - useful for mailto: links #### Returns `string` string

### Methods inherited from ViewableData

`ATT_val()`, `BaseHref()`, `CSSClasses()`, `ColumnBreak()`, `ColumnCalc()`, `ColumnNumber()`, `ColumnPad()`, `ColumnPos()`, `CurrentMember()`, `CurrentPage()`, `Debug()`, `Even()`, `EvenOdd()`, `First()`, `FirstLast()`, `HasPerm()`, `IsAjax()`, `JS_val()`, `Last()`, `Me()`, `Middle()`, `MiddleString()`, `Modulus()`, `MultipleOf()`, `Odd()`, `Pos()`, `RAW_val()`, `SQL_val()`, `ThemeDir()`, `ThemeName()`, `Top()`, `TotalItems()`, `XML_val()`, `__get()`, `__isset()`, `__set()`, `buildCastingCache()`, `cachedCall()`, `castingClass()`, `castingHelper()`, `castingHelperPair()`, `castingObjectCreator()`, `castingObjectCreatorPair()`, `customise()`, `defineMethods()`, `escapeTypeForField()`, `getField()`, `getIterator()`, `getSecurityID()`, `getXMLValues()`, `hasField()`, `hasValue()`, `i18nLocale()`, `iteratorProperties()`, `obj()`, `setCustomisedObj()`, `setField()`

### Methods inherited from Object

`__call()`, `__toString()`, `__wakeup()`, `addMethodsFrom()`, `addStaticVars()`, `addWrapperMethod()`, `add_extension()`, `add_static_var()`, `allMethodNames()`, `cacheToFile()`, `cacheToFileWithArgs()`, `clearCache()`, `combined_static()`, `create()`, `createMethod()`, `create_from_string()`, `exists()`, `extInstance()`, `extend()`, `getCustomClass()`, `getExtensionInstance()`, `getExtensionInstances()`, `get_extensions()`, `get_static()`, `hasExtension()`, `hasMethod()`, `has_extension()`, `invokeWithExtensions()`, `is_a()`, `loadCache()`, `parentClass()`, `parse_class_spec()`, `remove_extension()`, `sanitiseCachename()`, `saveCache()`, `set_stat()`, `set_static()`, `set_uninherited()`, `stat()`, `strong_create()`, `uninherited()`, `uninherited_static()`, `useCustomClass()`

### Magic methods summary

## Properties summary

`protected mixed` | $from | # #### Param string $from Email-Address
`protected mixed` | $to | # #### Param string $to Email-Address. Use comma-separation to pass multiple email-addresses.
`protected mixed` | $subject | # #### Param string $subject Subject of the email
`protected mixed` | $body | # #### Param string $body HTML content of the email. Passed straight into `Email::$ss_template` as $Body variable.
`protected mixed` | $plaintext_body | # #### Param string $plaintext_body Optional string for plaintext emails. If not set, defaults to converting the HTML-body with `Convert::xml2raw()`.
`protected mixed` | $cc | # #### Param string $cc
`protected mixed` | $bcc | # #### Param string $bcc
`protected static mixed` | $mailer | # #### Param Mailer $mailer Instance of a `Mailer` class.
`protected array` | $customHeaders | # #### Param array $customHeaders A map of header-name -> header-value
`protected array` | $attachments | # #### Param array $attachements Internal, use `Email::attachFileFromString()` or `Email::attachFile()`
`protected boolean` | $parseVariables_done | # #### Param boolean $
`protected string` | $ss_template | # #### Param string $ss_template The name of the used template (without *.ss extension)
`protected mixed` | $template_data | # #### Param array $template_data Additional data available in a template. Used in the same way than ViewableData->customize().
`protected mixed` | $bounceHandlerURL | # #### Param string $bounceHandlerURL
`public static string` | $admin_email_address | # #### Param sring $admin_email_address The default administrator email address. This will be set in the config on a site-by-site basis
`protected static mixed` | $send_all_emails_to | # #### Param string $send_all_emails_to Email-Address
`protected static mixed` | $bcc_all_emails_to | # #### Param string $bcc_all_emails_to Email-Address
`protected static mixed` | $cc_all_emails_to | # #### Param string $cc_all_emails_to Email-Address

### Properties inherited from ViewableData

`$casting`, `$customisedObject`, `$default_cast`, `$failover`, `$iteratorPos`, `$iteratorTotalItems`

### Properties inherited from Object

`$class`, `$extension_instances`, `$extensions`

[Raise a SilverStripe Framework issue/bug](https://github.com/silverstripe/silverstripe-framework/issues/new)
- [Raise a SilverStripe CMS issue/bug](https://github.com/silverstripe/silverstripe-cms/issues/new)
- Please use the Silverstripe Forums to ask development related questions. -