Skip to content

Move to the new DSN format for Mailer #12258

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 16, 2019
Merged

Move to the new DSN format for Mailer #12258

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Move to the new DSN format for Mailer
  • Loading branch information
@fabpot @javiereguiluz
fabpot authored and javiereguiluz committed Sep 16, 2019
commit c9febeecc35938ece9e1ccae7ddd8887bd2e6c18
48 changes: 33 additions & 15 deletions components/mailer.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,26 +85,44 @@ DSN::
$transport = Transport::fromDsn($dsn);

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
==================== ================================== ================================== ================================
``smtp://user:pass@example.com`` or ``sendmail+smtp://default`` to use the
``sendmail`` binary. To disable the transport, use ``null://null``.

For third-party providers, refers to the following table:

==================== ========================================== =========================================== ========================================
Provider SMTP HTTP API
==================== ========================================== =========================================== ========================================
Amazon SES ses+smtp://ACCESS_KEY:SECRET_KEY@default ses+https://ACCESS_KEY:SECRET_KEY@default ses+api://ACCESS_KEY:SECRET_KEY@default
Google Gmail gmail+smtp://USERNAME:PASSWORD@default n/a n/a
Mailchimp Mandrill mandrill+smtp://USERNAME:PASSWORD@default mandrill+https://KEY@default mandrill+api://KEY@default
Mailgun mailgun+smtp://USERNAME:PASSWORD@default mailgun+https://KEY:DOMAIN@default mailgun+api://KEY:DOMAIN@default
Postmark postmark+smtp://ID:ID@default n/a postmark+api://KEY@default
Sendgrid sendgrid+smtp://apikey:KEY@default n/a sendgrid+api://KEY@default
==================== ========================================== =========================================== ========================================

Instead of choosing a specific protocol, you can also let Symfony pick the
"best" one by omitting it from the scheme: for instance,
``mailgun://KEY:DOMAIN@default`` is equivalent to
``mailgun+https://KEY:DOMAIN@default``.

If you want to override the default host for a provider (to debug an issue with
a requestb.in like service), change ``default`` by your host:


.. code-block:: bash

mailgun+https://KEY:DOMAIN@example.com
mailgun+https://KEY:DOMAIN@example.com:99

Note that the protocol is *always* HTTPs and cannot be changed.

Failover Transport
------------------

You can create failover transport with the help of `||` operator::

$dsn = 'api://id@postmark || smtp://key@sendgrid';
$dsn = 'postmark+api://ID@default || sendgrid+smtp://KEY@default';

So if the first transport fails, the mailer will attempt to send through the
second transport.
Expand All @@ -115,7 +133,7 @@ Round Robin
If you want to send emails by using multiple transports in a round-robin fashion,
you can use the ``&&`` operator between the transports::

$dsn = 'api://id@postmark && smtp://key@sendgrid'
$dsn = 'postmark+api://ID@default && sendgrid+smtp://KEY@default';

Sending emails asynchronously
-----------------------------
Expand Down
27 changes: 17 additions & 10 deletions mailer.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,21 +64,28 @@ You'll now have a new line in your ``.env`` file that you can uncomment:

# .env
SENDGRID_KEY=
MAILER_DSN=smtp://$SENDGRID_KEY@sendgrid
MAILER_DSN=sendgrid://$SENDGRID_KEY@default

The ``MAILER_DSN`` isn't a *real* SMTP address: it's a simple format that offloads
most of the configuration work to mailer. The ``@sendgrid`` part of the address
activates the SendGrid mailer library that you just installed, which knows all
about how to deliver messages to SendGrid.
The ``MAILER_DSN`` isn't a *real* address: it's a simple format that offloads
most of the configuration work to mailer. The ``sendgrid`` scheme activates the
SendGrid provider that you just installed, which knows all about how to deliver
messages to SendGrid.

The *only* part you need to change is to set ``SENDGRID_KEY`` to your key (in
``.env`` or ``.env.local``).

Each transport will have different environment variables that the library will use
to configure the *actual* address and authentication for delivery. Some also have
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.
Each provider has different environment variables that the Mailer uses to
configure the *actual* protocol, address and authentication for delivery. Some
also have options that can be configured with query parameters at the end of the
``MAILER_DSN`` - like ``?region=`` for Amazon SES. Some providers support
sending via ``http``, ``api`` or ``smtp``. Symfony chooses the best available
transport, but you can force to use one:

.. code-block:: bash

# .env
# force to use SMTP instead of HTTP (which is the default)
MAILER_DSN=sendgrid+smtp://$SENDGRID_KEY@default

.. tip::

Expand Down