From 34907222804721e62b2e238351fbb2c950700a1e Mon Sep 17 00:00:00 2001 From: Philipp Rieber Date: Tue, 26 Nov 2013 07:41:26 +0100 Subject: [PATCH 1/3] [Cookbook] New cookbok: How to use the Cloud to send Emails --- cookbook/email/cloud.rst | 110 +++++++++++++++++++++++++++++++++++++++ cookbook/map.rst.inc | 1 + 2 files changed, 111 insertions(+) create mode 100644 cookbook/email/cloud.rst diff --git a/cookbook/email/cloud.rst b/cookbook/email/cloud.rst new file mode 100644 index 00000000000..52544a381ca --- /dev/null +++ b/cookbook/email/cloud.rst @@ -0,0 +1,110 @@ +.. index:: + single: Emails; 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. + +The following example shows how easy it is to integrate +`Amazon's Simple Email Services (SES)`_ into Symfony. But no matter what +service you're actually using, there's nothing more to it than configuring an +SMTP endpoint for Swift Mailer. + +In the Symfony configuration, change the Swift Mailer settings ``transport``, +``host``, ``port`` and ``encryption`` according to the information provided in +the `SES console`_. Create your individual SMTP credentials in the SES console +and complete the configuration with the provided ``username`` and ``password``: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + swiftmailer: + transport: smtp + host: email-smtp.us-east-1.amazonaws.com + port: 465 # different ports are available, see SES console + encryption: tls # TLS encryption is required + username: AWS_ACCESS_KEY # to be created in the SES console + password: AWS_SECRET_KEY # to be created in the SES console + + .. code-block:: xml + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('swiftmailer', array( + 'transport' => "smtp", + 'host' => "email-smtp.us-east-1.amazonaws.com", + 'port' => 465, + 'encryption' => "tls", + 'username' => "AWS_ACCESS_KEY", + 'password' => "AWS_SECRET_KEY", + )); + +The ``port`` and ``encryption`` keys are not present in the Symfony Standard +Edition configuration by default, but you can simply add them as needed. + +And that's it, you're ready to start sending emails through the cloud! + +.. tip:: + + If you are using the Symfony Standard Edition, configure the parameters at + ``parameters.yml`` and use them in your configuration files. This allows + for different Swift Mailer configurations for each installation of your + application. For instance, use Gmail during development and the cloud in + production. + + .. code-block:: yaml + + # app/config/parameters.yml + parameters: + # ... + mailer_transport: smtp + mailer_host: email-smtp.us-east-1.amazonaws.com + mailer_port: 465 # different ports are available, see SES console + mailer_encryption: tls # TLS encryption is required + mailer_user: AWS_ACCESS_KEY # to be created in the SES console + mailer_password: AWS_SECRET_KEY # to be created in the SES console + +.. 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 ``ReturnPath`` (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 Services (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/cookbook/map.rst.inc b/cookbook/map.rst.inc index ece47d25be9..2957912b752 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -66,6 +66,7 @@ * :doc:`/cookbook/email/email` * :doc:`/cookbook/email/gmail` + * :doc:`/cookbook/email/cloud` * :doc:`/cookbook/email/dev_environment` * :doc:`/cookbook/email/spool` * :doc:`/cookbook/email/testing` From 4f7c0f32a44bda556dfc795781ee5c114f1ae47e Mon Sep 17 00:00:00 2001 From: Philipp Rieber Date: Sun, 1 Dec 2013 07:32:10 +0100 Subject: [PATCH 2/3] Fixes and improvements after review --- cookbook/email/cloud.rst | 47 +++++++++++++++++++++------------------- cookbook/email/gmail.rst | 29 ++++++++++++++----------- cookbook/email/index.rst | 1 + 3 files changed, 42 insertions(+), 35 deletions(-) diff --git a/cookbook/email/cloud.rst b/cookbook/email/cloud.rst index 52544a381ca..729f4bec208 100644 --- a/cookbook/email/cloud.rst +++ b/cookbook/email/cloud.rst @@ -1,7 +1,7 @@ .. index:: - single: Emails; Cloud + single: Emails; Using the cloud -How to use the Cloud to send Emails +How to use the Cloud to Send Emails =================================== Requirements for sending emails from a production system differ from your @@ -38,30 +38,33 @@ and complete the configuration with the provided ``username`` and ``password``: .. code-block:: xml - - - - + xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd + http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd"> + + + + .. code-block:: php // app/config/config.php $container->loadFromExtension('swiftmailer', array( - 'transport' => "smtp", - 'host' => "email-smtp.us-east-1.amazonaws.com", - 'port' => 465, - 'encryption' => "tls", - 'username' => "AWS_ACCESS_KEY", - 'password' => "AWS_SECRET_KEY", + 'transport' => 'smtp', + 'host' => 'email-smtp.us-east-1.amazonaws.com', + 'port' => 465, + 'encryption' => 'tls', + 'username' => 'AWS_ACCESS_KEY', + 'password' => 'AWS_SECRET_KEY', )); The ``port`` and ``encryption`` keys are not present in the Symfony Standard @@ -71,7 +74,7 @@ And that's it, you're ready to start sending emails through the cloud! .. tip:: - If you are using the Symfony Standard Edition, configure the parameters at + If you are using the Symfony Standard Edition, configure the parameters in ``parameters.yml`` and use them in your configuration files. This allows for different Swift Mailer configurations for each installation of your application. For instance, use Gmail during development and the cloud in @@ -95,7 +98,7 @@ And that's it, you're ready to start sending emails through the cloud! * You have to sign up to `Amazon Web Services (AWS)`_; - * Every sender address used in the ``From`` or ``ReturnPath`` (bounce + * 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; diff --git a/cookbook/email/gmail.rst b/cookbook/email/gmail.rst index 11634282f0c..0aff06160b2 100644 --- a/cookbook/email/gmail.rst +++ b/cookbook/email/gmail.rst @@ -1,7 +1,7 @@ .. index:: single: Emails; Gmail -How to use Gmail to send Emails +How to use Gmail to Send Emails =============================== During development, instead of using a regular SMTP server to send emails, you @@ -29,31 +29,34 @@ In the development configuration file, change the ``transport`` setting to .. code-block:: xml - - + xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd + http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd"> - + + + .. code-block:: php // app/config/config_dev.php $container->loadFromExtension('swiftmailer', array( - 'transport' => "gmail", - 'username' => "your_gmail_username", - 'password' => "your_gmail_password", + 'transport' => 'gmail', + 'username' => 'your_gmail_username', + 'password' => 'your_gmail_password', )); You're done! .. tip:: - If you are using the Symfony Standard Edition, configure the parameters at ``parameters.yml``: + If you are using the Symfony Standard Edition, configure the parameters in ``parameters.yml``: .. code-block:: yaml diff --git a/cookbook/email/index.rst b/cookbook/email/index.rst index 7209fbcc652..351301f03e6 100644 --- a/cookbook/email/index.rst +++ b/cookbook/email/index.rst @@ -6,6 +6,7 @@ Email email gmail + cloud dev_environment spool testing From 6bbbc8a4fb9cafb172a9783f1177829716bdb081 Mon Sep 17 00:00:00 2001 From: Philipp Rieber Date: Sun, 1 Dec 2013 16:54:27 +0100 Subject: [PATCH 3/3] Fix wording and formatting --- cookbook/email/cloud.rst | 17 +++++++++++------ cookbook/email/gmail.rst | 3 ++- 2 files changed, 13 insertions(+), 7 deletions(-) diff --git a/cookbook/email/cloud.rst b/cookbook/email/cloud.rst index 729f4bec208..3f62afc746b 100644 --- a/cookbook/email/cloud.rst +++ b/cookbook/email/cloud.rst @@ -12,10 +12,14 @@ 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. -The following example shows how easy it is to integrate -`Amazon's Simple Email Services (SES)`_ into Symfony. But no matter what -service you're actually using, there's nothing more to it than configuring an -SMTP endpoint for Swift Mailer. +This cookbook 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 for + Swift Mailer. In the Symfony configuration, change the Swift Mailer settings ``transport``, ``host``, ``port`` and ``encryption`` according to the information provided in @@ -52,7 +56,8 @@ and complete the configuration with the provided ``username`` and ``password``: port="465" encryption="tls" username="AWS_ACCESS_KEY" - password="AWS_SECRET_KEY" /> + password="AWS_SECRET_KEY" + /> .. code-block:: php @@ -108,6 +113,6 @@ And that's it, you're ready to start sending emails through the cloud! * SES may be subject to a charge. -.. _`Amazon's Simple Email Services (SES)`: http://aws.amazon.com/ses +.. _`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/cookbook/email/gmail.rst b/cookbook/email/gmail.rst index 0aff06160b2..b37f35a442e 100644 --- a/cookbook/email/gmail.rst +++ b/cookbook/email/gmail.rst @@ -40,7 +40,8 @@ In the development configuration file, change the ``transport`` setting to + password="your_gmail_password" + /> .. code-block:: php