Thanks to visit codestin.com
Credit goes to github.com

Skip to content

[Mailer] Move to the new DSN format #12495

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 3 commits into from
Oct 16, 2019
Merged

[Mailer] Move to the new DSN format #12495

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
be392bc
Move to the new DSN format for Mailer
fabpot Sep 2, 2019
ca56502
Minor tweaks
javiereguiluz Sep 16, 2019
a2c607b
[Mailer] Move remaining DSN to new format
tucksaun Oct 16, 2019
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
46 changes: 31 additions & 15 deletions components/mailer.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,19 +85,35 @@ DSN::
$transport = Transport::fromDsn($dsn);

Where ``$dsn`` depends on the provider you want to use. For plain SMTP, use
``smtp://user:[email protected]`` 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:[email protected]`` or ``sendmail+smtp://default`` to use the
``sendmail`` binary. To disable the transport, use ``null://null``.

For third-party providers, refer 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 using
a service like ``requestbin.com``), change ``default`` by your host:

.. code-block:: bash

mailgun+https://KEY:[email protected]
mailgun+https://KEY:[email protected]:99

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

High Availability
-----------------
Expand All @@ -108,7 +124,7 @@ to ensure that emails are sent even if one mailer server fails .
A failover transport is configured with two or more transports and the
``failover`` keyword::

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

The mailer will start using the first transport. If the sending fails, the
mailer won't retry it with the other transports, but it will switch to the next
Expand All @@ -123,7 +139,7 @@ to distribute the mailing workload across multiple transports .
A round-robin transport is configured with two or more transports and the
``roundrobin`` keyword::

$dsn = 'roundrobin(api://id@postmark smtp://key@sendgrid)'
$dsn = 'roundrobin(postmark+api://ID@default sendgrid+smtp://KEY@default)'

The mailer will start using the first transport and if it fails, it will retry
the same delivery with the next transports until one of them succeeds (or until
Expand Down
29 changes: 18 additions & 11 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 Expand Up @@ -742,7 +749,7 @@ environment:
# config/packages/dev/mailer.yaml
framework:
mailer:
dsn: 'smtp://null'
dsn: 'null://null'

.. note::

Expand Down