Skip to content

Commit be392bc

Browse files
fabpottucksaun
fabpot
authored and
tucksaun
committed
Move to the new DSN format for Mailer
1 parent 27de64b commit be392bc

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
@@ -85,19 +85,37 @@ DSN::
8585
$transport = Transport::fromDsn($dsn);
8686

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

102120
High Availability
103121
-----------------
@@ -108,7 +126,7 @@ to ensure that emails are sent even if one mailer server fails .
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
@@ -123,7 +141,7 @@ to distribute the mailing workload across multiple transports .
123141
A round-robin transport is configured with two or more transports and the
124142
``roundrobin`` keyword::
125143

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

128146
The mailer will start using the first transport and if it fails, it will retry
129147
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
@@ -64,21 +64,28 @@ You'll now have a new line in your ``.env`` file that you can uncomment:
6464
6565
# .env
6666
SENDGRID_KEY=
67-
MAILER_DSN=smtp://$SENDGRID_KEY@sendgrid
67+
MAILER_DSN=sendgrid://$SENDGRID_KEY@default
6868
69-
The ``MAILER_DSN`` isn't a *real* SMTP address: it's a simple format that offloads
70-
most of the configuration work to mailer. The ``@sendgrid`` part of the address
71-
activates the SendGrid mailer library that you just installed, which knows all
72-
about how to deliver messages to SendGrid.
69+
The ``MAILER_DSN`` isn't a *real* address: it's a simple format that offloads
70+
most of the configuration work to mailer. The ``sendgrid`` scheme activates the
71+
SendGrid provider that you just installed, which knows all about how to deliver
72+
messages to SendGrid.
7373

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

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

0 commit comments

Comments
 (0)