Emails

Type

Class

Namespace

craft\commerce\services

Inherits

craft\commerce\services\Emails » yii\base\Component » yii\base\BaseObject

Implements

yii\base\Configurable

Since

2.0

Email service.

View source

Public Properties

Property	Description
allEmails	array, craft\commerce\models\Email[]
allEnabledEmails	craft\commerce\models\Email[]
behaviors	yii\base\Behavior – List of behaviors attached to this component.

allEmails

Type

array, craft\commerce\models\Email[]

Default value

null

View source

allEnabledEmails

Type

craft\commerce\models\Email[]

Default value

null

View source

Public Methods

Method	Description
__call()	Calls the named method which is not a class method.
__clone()	This method is called after the object is created by cloning an existing one.
__construct()	Constructor.
__get()	Returns the value of a component property.
__isset()	Checks if a property is set, i.e. defined and not null.
__set()	Sets the value of a component property.
__unset()	Sets a component property to be null.
attachBehavior()	Attaches a behavior to this component.
attachBehaviors()	Attaches a list of behaviors to the component.
behaviors()	Returns a list of behaviors that this component should behave as.
canGetProperty()	Returns a value indicating whether a property can be read.
canSetProperty()	Returns a value indicating whether a property can be set.
className()	Returns the fully qualified name of this class.
deleteEmailById()	Delete an email by its ID.
detachBehavior()	Detaches a behavior from the component.
detachBehaviors()	Detaches all behaviors from the component.
ensureBehaviors()	Makes sure that the behaviors declared in behaviors() are attached to this component.
getAllEmails()	Get all emails.
getAllEmailsByOrderStatusId()	Get all emails by an order status ID.
getAllEnabledEmails()	Get all emails that are enabled.
getBehavior()	Returns the named behavior object.
getBehaviors()	Returns all behaviors attached to this component.
getEmailById()	Get an email by its ID.
handleChangedEmail()	Handle email status change.
handleDeletedEmail()	Handle email getting deleted.
hasEventHandlers()	Returns a value indicating whether there is any handler attached to the named event.
hasMethod()	Returns a value indicating whether a method is defined.
hasProperty()	Returns a value indicating whether a property is defined for this component.
init()	Initializes the object.
off()	Detaches an existing event handler from this component.
on()	Attaches an event handler to an event.
saveEmail()	Save an email.
sendEmail()	Send a commerce email.
trigger()	Triggers an event.

deleteEmailById()

Delete an email by its ID.

View source

Arguments

• $id

getAllEmails()

Get all emails.

View source

Arguments

• $storeId (integer, null)

Returns

\Illuminate\Support\Collection<\craft\commerce\models\Email>

Throws

• yii\base\InvalidConfigException
• craft\errors\SiteNotFoundException

getAllEmailsByOrderStatusId()

Get all emails by an order status ID.

View source

Arguments

• $id

Returns

craft\commerce\models\Email[]

getAllEnabledEmails()

Get all emails that are enabled.

View source

Arguments

• $storeId (integer, null)

Returns

\Illuminate\Support\Collection<\craft\commerce\models\Email>

Throws

• yii\base\InvalidConfigException
• craft\errors\SiteNotFoundException

getEmailById()

Get an email by its ID.

View source

Arguments

• $id
• $storeId

handleChangedEmail()

Handle email status change.

View source

Arguments

• $event

Throws

• Throwable
  if reasons

handleDeletedEmail()

Handle email getting deleted.

View source

Arguments

• $event

Throws

• Throwable
• yii\db\StaleObjectException

saveEmail()

Save an email.

View source

Arguments

• $email
• $runValidation

Throws

• yii\base\Exception
• yii\base\ErrorException
• yii\base\NotSupportedException
• yii\web\ServerErrorHttpException

sendEmail()

Send a commerce email.

View source

Arguments

• $email
• $order
• $orderHistory
• $orderData (array, null) – Since the order may have changed by the time the email sends.
• $error (string) – The reason this method failed.

Returns

boolean – $result

Throws

• yii\base\Exception
• Throwable
• yii\base\InvalidConfigException

Protected Methods

Method	Description
clearCache()

clearCache()

Since

5.0.0

View source

Returns

void

Constants

Constant	Description
CONFIG_EMAILS_KEY

Events

EVENT_AFTER_DELETE_EMAIL

Type

craft\commerce\events\EmailEvent

The event that is triggered after an email is deleted.

use craft\commerce\events\EmailEvent;
use craft\commerce\services\Emails;
use craft\commerce\models\Email;
use yii\base\Event;

Event::on(
    Emails::class,
    Emails::EVENT_AFTER_DELETE_EMAIL,
    function(EmailEvent $event) {
        // @var Email $email
        $email = $event->email;

        // ...
    }
);

---

EVENT_AFTER_SAVE_EMAIL

Type

craft\commerce\events\EmailEvent

The event that is triggered after an email is saved.

use craft\commerce\events\EmailEvent;
use craft\commerce\services\Emails;
use craft\commerce\models\Email;
use yii\base\Event;

Event::on(
    Emails::class,
    Emails::EVENT_AFTER_SAVE_EMAIL,
    function(EmailEvent $event) {
        // @var Email $email
        $email = $event->email;
        // @var bool $isNew
        $isNew = $event->isNew;

        // ...
    }
);

---

EVENT_AFTER_SEND_MAIL

Type

craft\commerce\events\MailEvent

The event that is raised after an email is sent

Plugins can get notified after an email has been sent out.

use craft\commerce\events\MailEvent;
use craft\commerce\services\Emails;
use yii\base\Event;

Event::on(
    Emails::class,
    Emails::EVENT_AFTER_SEND_MAIL,
    function(MailEvent $event) {
        // @var Message $message
        $message = $event->craftEmail;
        // @var Email $email
        $email = $event->commerceEmail;
        // @var Order $order
        $order = $event->order;
        // @var OrderHistory $history
        $history = $event->orderHistory;

        // Add the email address to an external CRM
        // ...
    }
);

---

EVENT_BEFORE_DELETE_EMAIL

Type

craft\commerce\events\EmailEvent

The event that is triggered before an email is deleted.

use craft\commerce\events\EmailEvent;
use craft\commerce\services\Emails;
use craft\commerce\models\Email;
use yii\base\Event;

Event::on(
    Emails::class,
    Emails::EVENT_BEFORE_DELETE_EMAIL,
    function(EmailEvent $event) {
        // @var Email $email
        $email = $event->email;

        // ...
    }
);

---

EVENT_BEFORE_SAVE_EMAIL

Type

craft\commerce\events\EmailEvent

The event that is triggered before an email is saved.

use craft\commerce\events\EmailEvent;
use craft\commerce\services\Emails;
use craft\commerce\models\Email;
use yii\base\Event;

Event::on(
    Emails::class,
    Emails::EVENT_BEFORE_SAVE_EMAIL,
    function(EmailEvent $event) {
        // @var Email $email
        $email = $event->email;
        // @var bool $isNew
        $isNew = $event->isNew;

        // ...
    }
);

---

EVENT_BEFORE_SEND_MAIL

Type

craft\commerce\events\MailEvent

The event that is raised before an email is sent. You may set craft\commerce\events\MailEvent::$isValid to false to prevent the email from being sent.

Plugins can get notified before an email is being sent out.

use craft\commerce\events\MailEvent;
use craft\commerce\services\Emails;
use yii\base\Event;

Event::on(
    Emails::class,
    Emails::EVENT_BEFORE_SEND_MAIL,
    function(MailEvent $event) {
        // @var Message $message
        $message = $event->craftEmail;
        // @var Email $email
        $email = $event->commerceEmail;
        // @var Order $order
        $order = $event->order;
        // @var OrderHistory $history
        $history = $event->orderHistory;

        // Use `$event->isValid = false` to prevent sending
        // based on some business rules or client preferences
        // ...
    }
);

---