Skip to main content
Communicating with customers is an integral part of every business. In OroPlatform, email addresses are represented by the Oro\Bundle\EmailBundle\Entity\EmailAddress class. Every bundle can provide its own email templates and notification rules.

​
Email templates

Create reusable Twig-based email templates by providing a data fixture that extends AbstractEmailFixture: 
// src/Acme/Bundle/DemoBundle/Migrations/Data/ORM/EmailTemplatesFixture.php

namespace Acme\Bundle\DemoBundle\Migrations\Data\ORM;

use Oro\Bundle\EmailBundle\Migrations\Data\ORM\AbstractEmailFixture;

class EmailTemplatesFixture extends AbstractEmailFixture
{
    #[\Override]
    public function getEmailsDir(): string
    {
        return $this->container
            ->get('kernel')
            ->locateResource('@AcmeDemoBundle/Resources/emails');
    }
}

​
Template file format

The email format is determined by the template file extension:
ExtensionEmail format
.html.twig, .htmlHTML
.txt.twig, .txtPlaintext
HTML is used as the default if no format can be derived from the filename extension.

​
Template metadata parameters

Each template file must include metadata as Twig comment parameters:
ParameterMandatoryDescription
@entityNameYesFully-qualified class name of the email owner entity.
@subjectYesThe email subject.
@nameNoTemplate name shown in the UI (defaults to filename without extension).
@isSystemNoSet to 1 to mark as a system template.
@isEditableNoSet to 1 (with @isSystem=1) to allow editing via the UI.

​
Creating and sending emails

Create an Email model instance and populate it via setters:
use Oro\Bundle\EmailBundle\Form\Model\Email;

$email = new Email();
$email->setFrom('[email protected]');
$email->setTo(['[email protected]', '[email protected]']);
$email->setCc(['[email protected]']);
$email->setBcc(['[email protected]']);
$email->setSubject('...');
$email->setTemplate($emailTemplateEntity);
$email->setContexts([...]);
$email->setType('html'); // or 'text'
$email->setBody('...');  // alternative to setTemplate()
$email->addAttachment($attachment);

​
Sending the email

Use the oro_email.sender.email_model_sender service to send and persist the email: 
$processor = $this->get('oro_email.sender.email_model_sender');
$processor->send($email);
When send() is called, the mailer sender:
1

Creates a Symfony Email instance

Populates \Symfony\Component\Mime\Email with data from the Email model.
2

Determines the email origin

If no EmailOrigin is provided, one is created based on the sender address and selected organization.
3

Sends the email

Uses the application’s mailer configuration, or the user’s custom SMTP server if configured.
4

Persists the email

Stores the sent email and all context associations in the database.
5

Returns the persisted email user

Returns an instance of Oro\EmailBundle\Entity\EmailUser.

​
Email notifications

To receive emails when Doctrine entities are created, updated, or removed, create an EmailNotification data fixture: 
// src/Acme/Bundle/DemoBundle/Migrations/Data/ORM/CreateCommentNotification.php

use Oro\Bundle\NotificationBundle\Entity\EmailNotification;
use Oro\Bundle\NotificationBundle\Entity\RecipientList;

class CreateCommentNotification extends AbstractFixture
{
    public function load(ObjectManager $manager)
    {
        $notification = new EmailNotification();
        $notification->setEntityName('Acme\Bundle\DemoBundle\Entity\Comment');

        // Pre-defined event names:
        // oro.notification.event.entity_post_persist
        // oro.notification.event.entity_post_update
        // oro.notification.event.entity_post_remove
        $notification->setEventName('oro.notification.event.entity_post_persist');

        $recipients = new RecipientList();
        $group = $manager->getRepository('Oro\Bundle\UserBundle\Entity\Group')
            ->findOneByName('Moderator');
        $recipients->addGroup($group);
        $notification->setRecipientList($recipients);

        $template = $manager->getRepository('Oro\Bundle\EmailBundle\Entity\EmailTemplate')
            ->findByName('comment_created_notification');
        $notification->setTemplate($template);

        $manager->persist($notification);
        $manager->flush();
    }
}

​
Email address owners

Each email address belongs to exactly one entity (e.g., User, Contact). To make your own entity own an email address:
1

Implement the email entity

Create an entity implementing Oro\Bundle\EmailBundle\Entity\EmailInterface:
  • getEmailField() — column that holds the email address
  • getId() — unique identifier
  • getEmail() — the actual email address
  • getEmailOwner() — the owning entity
2

Implement the owner entity

Make the owner entity implement Oro\Bundle\EmailBundle\Entity\EmailOwnerInterface:
  • getClass() — fully qualified class name
  • getEmailFields() — list of email address properties
  • getId() — unique identifier
  • getFirstName() / getLastName() — used when building recipient names
3

Create an EmailOwnerProvider

Implement Oro\Bundle\EmailBundle\Entity\Provider\EmailOwnerProviderInterface and register it as a service tagged oro_email.owner.provider:
services:
    acme_demo.provider.email_owner_provider:
        class: Acme\Bundle\DemoBundle\Entity\Provider\EmailOwnerProvider
        tags:
            - { name: oro_email.owner.provider, order: 3 }
4

Update the database schema

php bin/console doctrine:schema:update --force
php bin/console cache:warmup

Build docs developers (and LLMs) love

Get started for freeTalk to us