diff --git a/_build/redirection_map b/_build/redirection_map index c3d1883329e..ed3b113730c 100644 --- a/_build/redirection_map +++ b/_build/redirection_map @@ -153,10 +153,10 @@ /cookbook/doctrine/reverse_engineering /doctrine/reverse_engineering /doctrine/repository /doctrine /doctrine/console /doctrine -/cookbook/email/cloud /email/cloud +/cookbook/email/cloud /email /cookbook/email/dev_environment /email/dev_environment /cookbook/email/email /email -/cookbook/email/gmail /email/gmail +/cookbook/email/gmail /email /cookbook/email/index /email /cookbook/email/spool /email/spool /cookbook/email/testing /email/testing @@ -361,6 +361,8 @@ /console/logging /console /deployment/tools /deployment /install/bundles /setup/bundles +/email/gmail /email +/email/cloud /email /event_dispatcher/class_extension /event_dispatcher /form /forms /form/use_virtual_forms /form/inherit_data_option diff --git a/email.rst b/email.rst index 501173490ad..714d8e0bec2 100644 --- a/email.rst +++ b/email.rst @@ -37,9 +37,6 @@ environment variable in the ``.env`` file: # use this to disable email delivery MAILER_URL=null://localhost - # use this to send emails via Gmail (don't use this in production) - MAILER_URL=gmail://username:password@localhost - # use this to configure a traditional SMTP server MAILER_URL=smtp://localhost:25?encryption=ssl&auth_mode=login&username=&password= @@ -107,6 +104,51 @@ The ``$message`` object supports many more options, such as including attachment adding HTML content, and much more. Refer to the `Creating Messages`_ section of the Swift Mailer documentation for more details. +.. _email-using-gmail: + +Using Gmail to Send Emails +-------------------------- + +During development, you might prefer to send emails using Gmail instead of +setting up a regular SMTP server. To do that, update the ``MAILER_URL`` of your +``.env`` file to this: + +.. code-block:: bash + + # username is your full Gmail or Google Apps email address + MAILER_URL=gmail://username:password@localhost + +The ``gmail`` transport is simply a shortcut that uses the ``smtp`` transport, +``ssl`` encryption, ``login`` auth mode and ``smtp.gmail.com`` host. If your app +uses other encryption or auth mode, you must override those values +(:doc:`see mailer config reference `): + +.. code-block:: bash + + # username is your full Gmail or Google Apps email address + MAILER_URL=gmail://username:password@localhost?encryption=tls&auth_mode=oauth + +If your Gmail account uses 2-Step-Verification, you must `generate an App password`_ +and use it as the value of the mailer password. You must also ensure that you +`allow less secure apps to access your Gmail account`_. + +Using Cloud Services to Send Emails +----------------------------------- + +Cloud mailing services are a popular option for companies that don't want to set +up and maintain their own reliable mail servers. In Symfony apps, using these +services is as simple as updating the value of ``MAILER_URL`` in the ``.env`` +file. For example, for `Amazon SES`_ (Simple Email Service): + +.. code-block:: bash + + # The host will be different depending on your AWS zone + # The username/password credentials are obtained from the Amazon SES console + MAILER_URL=smtp://email-smtp.us-east-1.amazonaws.com:587?encryption=tls&username=YOUR_SES_USERNAME&password=YOUR_SES_PASSWORD + +Use the same technique for other mail services, as most of the time there is +nothing more to it than configuring an SMTP endpoint. + Learn more ---------- @@ -114,8 +156,6 @@ Learn more :maxdepth: 1 email/dev_environment - email/gmail - email/cloud email/spool email/testing @@ -125,3 +165,5 @@ Learn more .. _`Mandrill`: https://mandrill.com/ .. _`SendGrid`: https://sendgrid.com/ .. _`Amazon SES`: http://aws.amazon.com/ses/ +.. _`generate an App password`: https://support.google.com/accounts/answer/185833 +.. _`allow less secure apps to access your Gmail account`: https://support.google.com/accounts/answer/6010255 diff --git a/email/cloud.rst b/email/cloud.rst deleted file mode 100644 index 3166405141f..00000000000 --- a/email/cloud.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. index:: - single: Emails; Using the cloud - -How to Use the Cloud to Send Emails -=================================== - -Requirements for sending emails from a production system differ from your -development setup as you don't want to be limited in the number of emails, -the sending rate or the sender address. Thus, -:doc:`using Gmail ` or similar services is not an -option. If setting up and maintaining your own reliable mail server causes -you a headache there's a simple solution: Leverage the cloud to send your -emails. - -This article shows how easy it is to integrate -`Amazon's Simple Email Service (SES)`_ into Symfony. - -.. note:: - - You can use the same technique for other mail services, as most of the - time there is nothing more to it than configuring an SMTP endpoint. - -Symfony's mailer uses the ``MAILER_URL`` environment variable to store the -SMTP connection parameters, including the security credentials. Get those -parameters from the `SES console`_ and update the value of ``MAILER_URL`` in -the ``.env`` file: - -.. code-block:: bash - - MAILER_URL=smtp://email-smtp.us-east-1.amazonaws.com:587?encryption=tls&username=YOUR_SES_USERNAME&password=YOUR_SES_PASSWORD - -And that's it, you're ready to start sending emails through the cloud! - -.. note:: - - If you intend to use Amazon SES, please note the following: - - * You have to sign up to `Amazon Web Services (AWS)`_; - - * Every sender address used in the ``From`` or ``Return-Path`` (bounce - address) header needs to be confirmed by the owner. You can also - confirm an entire domain; - - * Initially you are in a restricted sandbox mode. You need to request - production access before being allowed to send to arbitrary - recipients; - - * SES may be subject to a charge. - -.. _`Amazon's Simple Email Service (SES)`: http://aws.amazon.com/ses -.. _`SES console`: https://console.aws.amazon.com/ses -.. _`Amazon Web Services (AWS)`: http://aws.amazon.com diff --git a/email/gmail.rst b/email/gmail.rst deleted file mode 100644 index a8d456edaa4..00000000000 --- a/email/gmail.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. index:: - single: Emails; Gmail - -How to Use Gmail to Send Emails -=============================== - -During development, instead of using a regular SMTP server to send emails, you -might find using Gmail easier and more practical. The Symfony mailer makes -it really easy. - -In the ``.env`` file used in your development machine, change the ``MAILER_URL`` -environment variable to this: - -.. code-block:: bash - - MAILER_URL=gmail://YOUR_GMAIL_USERNAME:YOUR_GMAIL_PASSWORD@localhost - -Redefining the Default Configuration Parameters ------------------------------------------------ - -The ``gmail`` transport is simply a shortcut that uses the ``smtp`` transport -and sets these options: - -============== ================== -Option Value -============== ================== -``encryption`` ``ssl`` -``auth_mode`` ``login`` -``host`` ``smtp.gmail.com`` -============== ================== - -If your application uses ``tls`` encryption or ``oauth`` authentication, you -must override the default options by defining the ``encryption`` and ``auth_mode`` -parameters. - -If your Gmail account uses 2-Step-Verification, you must `generate an App password`_ -and use it as the value of the ``mailer_password`` parameter. You must also ensure -that you `allow less secure apps to access your Gmail account`_. - -.. seealso:: - - See the :doc:`Swiftmailer configuration reference ` - for more details. - -.. _`generate an App password`: https://support.google.com/accounts/answer/185833 -.. _`allow less secure apps to access your Gmail account`: https://support.google.com/accounts/answer/6010255 diff --git a/reference/configuration/swiftmailer.rst b/reference/configuration/swiftmailer.rst index a1b06c2af80..6dc96856e18 100644 --- a/reference/configuration/swiftmailer.rst +++ b/reference/configuration/swiftmailer.rst @@ -58,7 +58,7 @@ transport The exact transport method to use to deliver emails. Valid values are: * smtp -* gmail (see :doc:`/email/gmail`) +* gmail (see :ref:`email-using-gmail`) * mail (deprecated in SwiftMailer since version 5.4.5) * sendmail * null (same as setting `disable_delivery`_ to ``true``)