Skip to content

Commit bb5ba4a

Browse files
javiereguiluzjaviereguiluz
committed
minor #12258 Move to the new DSN format for Mailer (fabpot)
This PR was squashed before being merged into the master branch (closes #12258). Discussion ---------- Move to the new DSN format for Mailer Documents symfony/symfony#33424 Commits ------- c9febee Move to the new DSN format for Mailer
2 parents ee3f6bc + c9febee commit bb5ba4a

File tree

2 files changed

+50
-25
lines changed

2 files changed

+50
-25
lines changed

‎components/mailer.rst‎

Lines changed: 33 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -81,19 +81,37 @@ DSN::
8181
$transport = Transport::fromDsn($dsn);
8282

8383
Where ``$dsn`` depends on the provider you want to use. For plain SMTP, use
84-
``smtp://user:pass@example.com`` or ``smtp://sendmail`` to use the ``sendmail``
85-
binary. For third-party providers, refers to the following table:
86-
87-
==================== ================================== ================================== ================================
88-
Provider SMTP HTTP API
89-
==================== ================================== ================================== ================================
90-
Amazon SES smtp://ACCESS_KEY:SECRET_KEY@ses http://ACCESS_KEY:SECRET_KEY@ses api://ACCESS_KEY:SECRET_KEY@ses
91-
Google Gmail smtp://USERNAME:PASSWORD@gmail n/a n/a
92-
Mailchimp Mandrill smtp://USERNAME:PASSWORD@mandrill http://KEY@mandrill api://KEY@mandrill
93-
Mailgun smtp://USERNAME:PASSWORD@mailgun http://KEY:DOMAIN@mailgun api://KEY:DOMAIN@mailgun
94-
Postmark smtp://ID:ID@postmark n/a api://KEY@postmark
95-
Sendgrid smtp://apikey:KEY@sendgrid n/a api://KEY@sendgrid
96-
==================== ================================== ================================== ================================
84+
``smtp://user:pass@example.com`` or ``sendmail+smtp://default`` to use the
85+
``sendmail`` binary. To disable the transport, use ``null://null``.
86+
87+
For third-party providers, refers to the following table:
88+
89+
==================== ========================================== =========================================== ========================================
90+
Provider SMTP HTTP API
91+
==================== ========================================== =========================================== ========================================
92+
Amazon SES ses+smtp://ACCESS_KEY:SECRET_KEY@default ses+https://ACCESS_KEY:SECRET_KEY@default ses+api://ACCESS_KEY:SECRET_KEY@default
93+
Google Gmail gmail+smtp://USERNAME:PASSWORD@default n/a n/a
94+
Mailchimp Mandrill mandrill+smtp://USERNAME:PASSWORD@default mandrill+https://KEY@default mandrill+api://KEY@default
95+
Mailgun mailgun+smtp://USERNAME:PASSWORD@default mailgun+https://KEY:DOMAIN@default mailgun+api://KEY:DOMAIN@default
96+
Postmark postmark+smtp://ID:ID@default n/a postmark+api://KEY@default
97+
Sendgrid sendgrid+smtp://apikey:KEY@default n/a sendgrid+api://KEY@default
98+
==================== ========================================== =========================================== ========================================
99+
100+
Instead of choosing a specific protocol, you can also let Symfony pick the
101+
"best" one by omitting it from the scheme: for instance,
102+
``mailgun://KEY:DOMAIN@default`` is equivalent to
103+
``mailgun+https://KEY:DOMAIN@default``.
104+
105+
If you want to override the default host for a provider (to debug an issue with
106+
a requestb.in like service), change ``default`` by your host:
107+
108+
109+
.. code-block:: bash
110+
111+
mailgun+https://KEY:DOMAIN@example.com
112+
mailgun+https://KEY:DOMAIN@example.com:99
113+
114+
Note that the protocol is *always* HTTPs and cannot be changed.
97115

98116
Load Balancing
99117
--------------
@@ -108,7 +126,7 @@ Failover Load Balancing
108126
A failover transport is configured with two or more transports and the
109127
``failover`` keyword::
110128

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

113131
The mailer will start using the first transport. If the sending fails, the
114132
mailer won't retry it with the other transports, but it will switch to the next
@@ -120,7 +138,7 @@ Round-Robin Load Balancing
120138
A round-robin transport is configured with two or more transports and the
121139
``roundrobin`` keyword::
122140

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

125143
The mailer will start using the first transport and if it fails, it will retry
126144
the same delivery with the next transports until one of them succeeds (or until

‎mailer.rst‎

Lines changed: 17 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -59,21 +59,28 @@ You'll now have a new line in your ``.env`` file that you can uncomment:
5959
6060
# .env
6161
SENDGRID_KEY=
62-
MAILER_DSN=smtp://$SENDGRID_KEY@sendgrid
62+
MAILER_DSN=sendgrid://$SENDGRID_KEY@default
6363
64-
The ``MAILER_DSN`` isn't a *real* SMTP address: it's a simple format that offloads
65-
most of the configuration work to mailer. The ``@sendgrid`` part of the address
66-
activates the SendGrid mailer library that you just installed, which knows all
67-
about how to deliver messages to SendGrid.
64+
The ``MAILER_DSN`` isn't a *real* address: it's a simple format that offloads
65+
most of the configuration work to mailer. The ``sendgrid`` scheme activates the
66+
SendGrid provider that you just installed, which knows all about how to deliver
67+
messages to SendGrid.
6868

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

72-
Each transport will have different environment variables that the library will use
73-
to configure the *actual* address and authentication for delivery. Some also have
74-
options that can be configured with query parameters on end of the ``MAILER_DSN`` -
75-
like ``?region=`` for Amazon SES. Some transports support sending via ``http``
76-
or ``smtp`` - both work the same, but ``http`` is recommended when available.
72+
Each provider has different environment variables that the Mailer uses to
73+
configure the *actual* protocol, address and authentication for delivery. Some
74+
also have options that can be configured with query parameters at the end of the
75+
``MAILER_DSN`` - like ``?region=`` for Amazon SES. Some providers support
76+
sending via ``http``, ``api`` or ``smtp``. Symfony chooses the best available
77+
transport, but you can force to use one:
78+
79+
.. code-block:: bash
80+
81+
# .env
82+
# force to use SMTP instead of HTTP (which is the default)
83+
MAILER_DSN=sendgrid+smtp://$SENDGRID_KEY@default
7784
7885
.. tip::
7986

0 commit comments

Comments
 (0)