From 375744b9c74aec78ed2fc91f10290a6a915dba3b Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Wed, 7 Aug 2019 15:12:39 +0200 Subject: [PATCH] Mailer doc tweaks --- components/mailer.rst | 63 +++++++++++++++++++++++++------------------ mailer.rst | 9 +++++++ 2 files changed, 46 insertions(+), 26 deletions(-) diff --git a/components/mailer.rst b/components/mailer.rst index 086d9805936..99797acc91e 100644 --- a/components/mailer.rst +++ b/components/mailer.rst @@ -41,9 +41,9 @@ The ``$email`` object is created via the :doc:`Mime component Transport --------- -The only transport that comes pre-installed with mailer is Smtp. +The only transport that comes pre-installed is SMTP. -Below is the list of other popular providers with built in support. +Below is the list of other popular providers with built-in support: ================== ============================================= Service Install with @@ -56,12 +56,15 @@ Postmark ``composer require symfony/postmark-mailer`` SendGrid ``composer require symfony/sendgrid-mailer`` ================== ============================================= -For example, suppose you want to use Google's Gmail. First, install it: +For example, suppose you want to use Google's Gmail SMTP server. First, install +it: .. code-block:: terminal $ composer require symfony/google-mailer +Then, use the SMTP Gmail transport: + .. code-block:: php use Symfony\Component\Mailer\Bridge\Google\Smtp\GmailTransport; @@ -70,30 +73,36 @@ For example, suppose you want to use Google's Gmail. First, install it: $mailer = new Mailer($transport); $mailer->send($email); -Use a DSN ---------- +Each provider provides up to 3 transports: standard SMTP, HTTP (it uses the +provider's API but the body is created by the mailer component), API (it uses +the full API of the provider with no control over the body creation -- features +might be limited as well). -The mailer component provides a convenient way to create transport object from -DSN string:: +.. _mailer_dsn: + +The mailer component provides a convenient way to create a transport from a +DSN:: use Symfony\Component\Mailer\Transport; $transport = Transport::fromDsn($dsn); -Where ``$dsn`` as one of the form below. - -- ``smtp://user:pass@gmail`` -- ``smtp://key@sendgrid`` -- ``smtp://null`` -- ``smtp://user:pass@mailgun`` -- ``http://key:domain@mailgun`` -- ``api://id@postmark`` - -This provides a unified behavior across all providers. -Easily switch from SMTP in development to a "real" provider in production -with same API. - -Failover transport +Where ``$dsn`` depends on the provider you want to use. For plain SMTP, use +``smtp://user:pass@example.com`` or ``smtp://sendmail`` to use the ``sendmail`` +binary. For third-party providers, refers to the following table: + +==================== ================================== ================================== ================================ + Provider SMTP HTTP API +==================== ================================== ================================== ================================ + Amazon SES smtp://ACCESS_KEY:SECRET_KEY@ses http://ACCESS_KEY:SECRET_KEY@ses api://ACCESS_KEY:SECRET_KEY@ses + Google Gmail smtp://USERNAME:PASSWORD@gmail n/a n/a + Mailchimp Mandrill smtp://USERNAME:PASSWORD@mandrill http://KEY@mandrill api://KEY@mandrill + Mailgun smtp://USERNAME:PASSWORD@mailgun http://KEY:DOMAIN@mailgun api://KEY:DOMAIN@mailgun + Postmark smtp://ID:ID@postmark n/a api://KEY@postmark + Sendgrid smtp://apikey:KEY@sendgrid n/a api://KEY@sendgrid +==================== ================================== ================================== ================================ + +Failover Transport ------------------ You can create failover transport with the help of `||` operator:: @@ -111,11 +120,11 @@ you can use the ``&&`` operator between the transports:: $dsn = 'api://id@postmark && smtp://key@sendgrid' -Async ------ +Sending emails asynchronously +----------------------------- -If you want to use the async functionality you need to install the -:doc:`Messenger component `. +If you want to send emails asynchronously, install the :doc:`Messenger component +`. .. code-block:: terminal @@ -145,11 +154,13 @@ Then, instantiate and pass a ``MessageBus`` as a second argument to ``Mailer``:: ]); $mailer = new Mailer($transport, $bus); + $mailer->send($email); + // you can pass an optional Envelope $mailer->send($email, new SmtpEnvelope( new Address('sender@example.com'), [ - new Address('recepient@example.com'), + new Address('recipient@example.com'), ] )); diff --git a/mailer.rst b/mailer.rst index c7fded70b84..08fdf9955a5 100644 --- a/mailer.rst +++ b/mailer.rst @@ -33,6 +33,11 @@ can deliver emails over ``smtp`` by configuring your ``.env`` file: # .env MAILER_DSN=smtp://user:pass@smtp.example.com +.. warning:: + + If you are migrating from Swiftmailer (and the Swiftmailer bundle), be + warned that the DSN format is different. + Using a 3rd Party Transport ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -80,6 +85,10 @@ options that can be configured with query parameters on end of the ``MAILER_DSN` like ``?region=`` for Amazon SES. Some transports support sending via ``http`` or ``smtp`` - both work the same, but ``http`` is recommended when available. +.. tip:: + + Check the :ref:`DSN formats ` for all supported providers. + Creating & Sending Messages ---------------------------