1
0
Fork 0
mirror of https://github.com/rails/rails.git synced 2022-11-09 12:12:34 -05:00
rails--rails/actionmailer/README.rdoc

142 lines
4.5 KiB
Text
Raw Normal View History

= Action Mailer -- Easy email delivery and testing
Action Mailer is a framework for designing email service layers. These layers
are used to consolidate code for sending out forgotten passwords, welcome
wishes on signup, invoices for billing, and any other use case that requires
a written notification to either a person or another system.
Action Mailer is in essence a wrapper around Action Controller and the
Mail gem. It provides a way to make emails using templates in the same
way that Action Controller renders views using templates.
Additionally, an Action Mailer class can be used to process incoming email,
such as allowing a blog to accept new posts from an email (which could even
have been sent from a phone).
You can read more about Action Mailer in the {Action Mailer Basics}[https://edgeguides.rubyonrails.org/action_mailer_basics.html] guide.
== Sending emails
The framework works by initializing any instance variables you want to be
available in the email template, followed by a call to +mail+ to deliver
the email.
This can be as simple as:
class Notifier < ActionMailer::Base
2012-04-28 00:58:15 -04:00
default from: 'system@loudthinking.com'
def welcome(recipient)
@recipient = recipient
2012-04-28 00:58:15 -04:00
mail(to: recipient,
subject: "[Signed up] Welcome #{recipient}")
end
end
The body of the email is created by using an Action View template (regular
2011-04-03 03:59:37 -04:00
ERB) that has the instance variables that are declared in the mailer action.
So the corresponding body template for the method above could look like this:
Hello there,
Mr. <%= @recipient %>
Thank you for signing up!
2011-12-23 00:10:01 -05:00
If the recipient was given as "david@loudthinking.com", the email
generated would look like this:
Date: Mon, 25 Jan 2010 22:48:09 +1100
From: system@loudthinking.com
To: david@loudthinking.com
Message-ID: <4b5d84f9dd6a5_7380800b81ac29578@void.loudthinking.com.mail>
Subject: [Signed up] Welcome david@loudthinking.com
Mime-Version: 1.0
Content-Type: text/plain;
charset="US-ASCII";
Content-Transfer-Encoding: 7bit
Hello there,
Mr. david@loudthinking.com
2011-09-26 13:46:25 -04:00
Thank you for signing up!
In order to send mails, you simply call the method and then call +deliver_now+ on the return value.
Calling the method returns a Mail Message object:
message = Notifier.welcome("david@loudthinking.com") # => Returns a Mail::Message object
message.deliver_now # => delivers the email
Or you can just chain the methods together like:
Notifier.welcome("david@loudthinking.com").deliver_now # Creates the email and sends it immediately
2011-04-03 07:17:26 -04:00
== Setting defaults
It is possible to set default values that will be used in every method in your
Action Mailer class. To implement this functionality, you just call the public
class method +default+ which you get for free from <tt>ActionMailer::Base</tt>.
This method accepts a Hash as the parameter. You can use any of the headers,
email messages have, like +:from+ as the key. You can also pass in a string as
the key, like "Content-Type", but Action Mailer does this out of the box for you,
so you won't need to worry about that. Finally, it is also possible to pass in a
Proc that will get evaluated when it is needed.
Note that every value you set with this method will get overwritten if you use the
same key in your mailer method.
2011-04-03 07:17:26 -04:00
Example:
2012-02-12 01:52:12 -05:00
class AuthenticationMailer < ActionMailer::Base
default from: "awesome@application.com", subject: Proc.new { "E-mail was generated at #{Time.now}" }
2011-04-03 07:17:26 -04:00
.....
end
== Configuration
The Base class has the full list of configuration options. Here's an example:
Merge documentation changes from docrails. commit 0fc3381aa5359f31b36057d7bfba2e0eb6a3c064 Author: Xavier Noria <fxn@hashref.com> Date: Fri May 16 23:44:51 2008 +0200 Conventions. Formatting. Revising docs all over the rails. This revision encourages the modern resource-oriented form_for usage. In addition corrects some markup and other details. commit 70e4bcf5cb039bea073851faed2df9f465e6f2f8 Author: Chris Kampmeier <chris@kampers.net> Date: Fri May 16 12:09:46 2008 -0700 Fix a couple spelling errors in docs commit 6ea5e4208f724b50e774e6a1af027336c3ee3de1 Author: Chris O'Sullivan <thechrisoshow@gmail.com> Date: Fri May 16 16:09:11 2008 +0100 Added docs about source_type for has_one association commit a01a0178be297b0eb62909819a15a01c6b69a841 Author: miloops <miloops@gmail.com> Date: Wed May 14 09:22:39 2008 +0000 Change migration generator USAGE to explain the timestamped migrations behaviour commit 4e2bc02163aa646ab1304b1b5bec98a7af8927f5 Author: Xavier Noria <fxn@hashref.com> Date: Fri May 16 00:43:03 2008 +0200 minor revision in url_for docs Made explicit that RESTful and controller/action styles are not interchangeable, and revised some markup. commit d6ecce66f4e125531875006eea8022b73fe135b5 Author: Michael Hartl <michael@michaelhartl.com> Date: Thu May 15 10:46:40 2008 -0700 Expanded and updated the link_to documentation commit b8c46c86f0b785f6afc3c58eeb1b347543f5901e Author: Cody Fauser <cody@jadedpixel.com> Date: Wed May 14 09:10:02 2008 -0400 Improve and cleanup ActionMailer documentation commit 9546ee299952c86329c4854f9b3776382c0575ff Author: Yehuda Katz <wycats@gmail.com> Date: Mon May 12 23:41:43 2008 -0700 Add documentation for Inflector.inflections commit cbd5db8f5165f013069b02414f9bf762d88f619f Author: Manik Juneja <mjuneja@manik-junejas-computer.local> Date: Mon May 12 23:43:31 2008 +0530 minor changes in railties/README. Added dbconsole introduction commit 130a280ddee1f96ccf378b52c17ee742b5e54f4a Author: Gaurav Sharma <gaurav@norbauer.com> Date: Mon May 12 18:00:19 2008 +0530 adding documentation for cached_attributes commit 164c9586480f0a02522ea15ec7fb42c6a783a74d Author: TomK32 <tomk32@tomk32.de> Date: Mon May 12 10:59:33 2008 +0200 proper heading for "Example:" commit 35634feb474cc55fbc95edeffe98cec241d45f23 Author: Matt Boehlig <thetamind@gmail.com> Date: Sun May 11 16:46:07 2008 -0500 Cleanup whitespace and change_table documentation commit 80bba28a1a56a0cafeb0fc94659905e88129bc31 Author: Xavier Noria <fxn@hashref.com> Date: Sun May 11 02:54:02 2008 +0200 documented the source annotation extractor commit e6823bb1650d9b0fea58bd2d355f388961a408b3 Author: Mike Mondragon <mikemondragon@gmail.com> Date: Fri May 9 13:49:56 2008 -0700 Added additional information about processing email with ActionMailer and the strategy one might want to employ to do so. commit e6afd8b2736364322b673bbdcca3e9b38b6d3da0 Author: Xavier Noria <fxn@hashref.com> Date: Thu May 8 23:49:36 2008 +0200 corrected and completed docs of increment/decrement/toggle in AR::Base commit 2fead68b3192332eee27945ed95a94a64ca73f70 Author: Austin Putman <austin@emmanuel.local> Date: Wed May 7 19:35:46 2008 -0700 Documented class methods on ActionController::Routing. These are dangerous, and mostly used for testing. commit f5b84182dbc39bea79c8ee319c688d00fa99f9d1 Author: Teflon Ted <github@rudiment.net> Date: Wed May 7 16:08:49 2008 -0400 Added explanation about errant inflections not being patched in the future in order to avoid breaking legacy applications. commit 370f4f51722cec49ace17093d29e9ce9e8f15cfb Author: Sunny Ripert <negatif@gmail.com> Date: Wed May 7 14:00:59 2008 +0200 Applied list conventions in AR::Base commit 5bd18429f09d44e75191bec42a6db04bd33f3030 Author: Sunny Ripert <negatif@gmail.com> Date: Wed May 7 13:53:35 2008 +0200 Renamed Options list to Attributes list whenever they weren't option hashes in AR::Base commit 2fa628e34b25166afb49e3afeea87e770ab84256 Author: Xavier Noria <fxn@hashref.com> Date: Wed May 7 11:52:33 2008 +0200 revised details in Exceptions section of AR::Base docs commit d912bd5672316454457ae83f6e9dda5197beeb6f Author: Yaroslav Markin <yaroslav@markin.net> Date: Wed May 7 13:50:28 2008 +0400 Add a filter_parameter_logging usage hint to generated ApplicationController. This may help to remind the developer to filter sensitive information from application logs. Closes #11578 commit f81d771f0657ae8375b84a77a059812cce5d6fd9 Author: Jack Danger Canty <git@6brand.com> Date: Tue May 6 23:35:05 2008 -0700 doc: ActiveRecord::Reflection::AssociationReflection#through_reflection Added documentation demonstrating the use of #through_reflection for finding intervening reflection objects for HasManyThrough and HasOneThrough. commit ae6b46f00b5b8b2939c6b37ce3329c83de7e71db Author: Cheah Chu Yeow <chuyeow@gmail.com> Date: Wed May 7 13:47:41 2008 +0800 Document AttributeAssignmentError and MultiparameterAssignmentErrors. commit 8f463550b597db2156b67733f31aed13487fbc3a Author: John Barnette <jbarnette@gmail.com> Date: Tue May 6 22:46:44 2008 -0700 Killing/fixing a bunch of outdated language in the AR README. commit 284a930a93fbee16e25d06392779dbf2f03e9e12 Author: Jonathan Dance <jd@wuputah.com> Date: Tue May 6 14:58:26 2008 -0400 improvements to the page caching docs commit 9482da621390c874da7c921c8bd6230caae7035a Author: Sunny Ripert <negatif@gmail.com> Date: Mon May 5 18:13:40 2008 +0200 validates_numericality_of() "integer" option really is "only_integer" commit e9afd6790a8f530528f6597a7f59bb283be754f6 Author: Sunny Ripert <negatif@gmail.com> Date: Mon May 5 12:11:59 2008 +0200 Harmonized hash notation in AR::Base commit 67ebf14a91ffd970b582be4ff2991d691a9cf3e1 Author: Sunny Ripert <negatif@gmail.com> Date: Mon May 5 12:06:19 2008 +0200 Turned options into rdoc-lists in AR::Base commit 0ec7c0a41d889d4e5382b9dff72f1aaba89bf297 Author: Marshall Huss <mwhuss@Macbook.local> Date: Sun May 4 23:21:33 2008 -0400 Added information of how to set element_name in the case the user has a name confliction with an existing model Signed-off-by: Pratik Naik <pratiknaik@gmail.com>
2008-05-16 18:01:32 -04:00
ActionMailer::Base.smtp_settings = {
address: 'smtp.yourserver.com', # default: localhost
port: '25', # default: 25
user_name: 'user',
password: 'pass',
authentication: :plain # :plain, :login or :cram_md5
Merge documentation changes from docrails. commit 0fc3381aa5359f31b36057d7bfba2e0eb6a3c064 Author: Xavier Noria <fxn@hashref.com> Date: Fri May 16 23:44:51 2008 +0200 Conventions. Formatting. Revising docs all over the rails. This revision encourages the modern resource-oriented form_for usage. In addition corrects some markup and other details. commit 70e4bcf5cb039bea073851faed2df9f465e6f2f8 Author: Chris Kampmeier <chris@kampers.net> Date: Fri May 16 12:09:46 2008 -0700 Fix a couple spelling errors in docs commit 6ea5e4208f724b50e774e6a1af027336c3ee3de1 Author: Chris O'Sullivan <thechrisoshow@gmail.com> Date: Fri May 16 16:09:11 2008 +0100 Added docs about source_type for has_one association commit a01a0178be297b0eb62909819a15a01c6b69a841 Author: miloops <miloops@gmail.com> Date: Wed May 14 09:22:39 2008 +0000 Change migration generator USAGE to explain the timestamped migrations behaviour commit 4e2bc02163aa646ab1304b1b5bec98a7af8927f5 Author: Xavier Noria <fxn@hashref.com> Date: Fri May 16 00:43:03 2008 +0200 minor revision in url_for docs Made explicit that RESTful and controller/action styles are not interchangeable, and revised some markup. commit d6ecce66f4e125531875006eea8022b73fe135b5 Author: Michael Hartl <michael@michaelhartl.com> Date: Thu May 15 10:46:40 2008 -0700 Expanded and updated the link_to documentation commit b8c46c86f0b785f6afc3c58eeb1b347543f5901e Author: Cody Fauser <cody@jadedpixel.com> Date: Wed May 14 09:10:02 2008 -0400 Improve and cleanup ActionMailer documentation commit 9546ee299952c86329c4854f9b3776382c0575ff Author: Yehuda Katz <wycats@gmail.com> Date: Mon May 12 23:41:43 2008 -0700 Add documentation for Inflector.inflections commit cbd5db8f5165f013069b02414f9bf762d88f619f Author: Manik Juneja <mjuneja@manik-junejas-computer.local> Date: Mon May 12 23:43:31 2008 +0530 minor changes in railties/README. Added dbconsole introduction commit 130a280ddee1f96ccf378b52c17ee742b5e54f4a Author: Gaurav Sharma <gaurav@norbauer.com> Date: Mon May 12 18:00:19 2008 +0530 adding documentation for cached_attributes commit 164c9586480f0a02522ea15ec7fb42c6a783a74d Author: TomK32 <tomk32@tomk32.de> Date: Mon May 12 10:59:33 2008 +0200 proper heading for "Example:" commit 35634feb474cc55fbc95edeffe98cec241d45f23 Author: Matt Boehlig <thetamind@gmail.com> Date: Sun May 11 16:46:07 2008 -0500 Cleanup whitespace and change_table documentation commit 80bba28a1a56a0cafeb0fc94659905e88129bc31 Author: Xavier Noria <fxn@hashref.com> Date: Sun May 11 02:54:02 2008 +0200 documented the source annotation extractor commit e6823bb1650d9b0fea58bd2d355f388961a408b3 Author: Mike Mondragon <mikemondragon@gmail.com> Date: Fri May 9 13:49:56 2008 -0700 Added additional information about processing email with ActionMailer and the strategy one might want to employ to do so. commit e6afd8b2736364322b673bbdcca3e9b38b6d3da0 Author: Xavier Noria <fxn@hashref.com> Date: Thu May 8 23:49:36 2008 +0200 corrected and completed docs of increment/decrement/toggle in AR::Base commit 2fead68b3192332eee27945ed95a94a64ca73f70 Author: Austin Putman <austin@emmanuel.local> Date: Wed May 7 19:35:46 2008 -0700 Documented class methods on ActionController::Routing. These are dangerous, and mostly used for testing. commit f5b84182dbc39bea79c8ee319c688d00fa99f9d1 Author: Teflon Ted <github@rudiment.net> Date: Wed May 7 16:08:49 2008 -0400 Added explanation about errant inflections not being patched in the future in order to avoid breaking legacy applications. commit 370f4f51722cec49ace17093d29e9ce9e8f15cfb Author: Sunny Ripert <negatif@gmail.com> Date: Wed May 7 14:00:59 2008 +0200 Applied list conventions in AR::Base commit 5bd18429f09d44e75191bec42a6db04bd33f3030 Author: Sunny Ripert <negatif@gmail.com> Date: Wed May 7 13:53:35 2008 +0200 Renamed Options list to Attributes list whenever they weren't option hashes in AR::Base commit 2fa628e34b25166afb49e3afeea87e770ab84256 Author: Xavier Noria <fxn@hashref.com> Date: Wed May 7 11:52:33 2008 +0200 revised details in Exceptions section of AR::Base docs commit d912bd5672316454457ae83f6e9dda5197beeb6f Author: Yaroslav Markin <yaroslav@markin.net> Date: Wed May 7 13:50:28 2008 +0400 Add a filter_parameter_logging usage hint to generated ApplicationController. This may help to remind the developer to filter sensitive information from application logs. Closes #11578 commit f81d771f0657ae8375b84a77a059812cce5d6fd9 Author: Jack Danger Canty <git@6brand.com> Date: Tue May 6 23:35:05 2008 -0700 doc: ActiveRecord::Reflection::AssociationReflection#through_reflection Added documentation demonstrating the use of #through_reflection for finding intervening reflection objects for HasManyThrough and HasOneThrough. commit ae6b46f00b5b8b2939c6b37ce3329c83de7e71db Author: Cheah Chu Yeow <chuyeow@gmail.com> Date: Wed May 7 13:47:41 2008 +0800 Document AttributeAssignmentError and MultiparameterAssignmentErrors. commit 8f463550b597db2156b67733f31aed13487fbc3a Author: John Barnette <jbarnette@gmail.com> Date: Tue May 6 22:46:44 2008 -0700 Killing/fixing a bunch of outdated language in the AR README. commit 284a930a93fbee16e25d06392779dbf2f03e9e12 Author: Jonathan Dance <jd@wuputah.com> Date: Tue May 6 14:58:26 2008 -0400 improvements to the page caching docs commit 9482da621390c874da7c921c8bd6230caae7035a Author: Sunny Ripert <negatif@gmail.com> Date: Mon May 5 18:13:40 2008 +0200 validates_numericality_of() "integer" option really is "only_integer" commit e9afd6790a8f530528f6597a7f59bb283be754f6 Author: Sunny Ripert <negatif@gmail.com> Date: Mon May 5 12:11:59 2008 +0200 Harmonized hash notation in AR::Base commit 67ebf14a91ffd970b582be4ff2991d691a9cf3e1 Author: Sunny Ripert <negatif@gmail.com> Date: Mon May 5 12:06:19 2008 +0200 Turned options into rdoc-lists in AR::Base commit 0ec7c0a41d889d4e5382b9dff72f1aaba89bf297 Author: Marshall Huss <mwhuss@Macbook.local> Date: Sun May 4 23:21:33 2008 -0400 Added information of how to set element_name in the case the user has a name confliction with an existing model Signed-off-by: Pratik Naik <pratiknaik@gmail.com>
2008-05-16 18:01:32 -04:00
}
== Download and installation
2011-08-05 04:34:43 -04:00
The latest version of Action Mailer can be installed with RubyGems:
$ gem install actionmailer
2017-11-28 13:27:43 -05:00
Source code can be downloaded as part of the Rails project on GitHub:
* https://github.com/rails/rails/tree/main/actionmailer
== License
Action Mailer is released under the MIT license:
2017-08-21 19:46:02 -04:00
* https://opensource.org/licenses/MIT
== Support
API documentation is at
* https://api.rubyonrails.org
2017-11-28 13:27:43 -05:00
Bug reports for the Ruby on Rails project can be filed here:
2011-05-10 12:30:06 -04:00
* https://github.com/rails/rails/issues
2011-03-04 19:38:21 -05:00
Feature requests should be discussed on the rails-core mailing list here:
* https://discuss.rubyonrails.org/c/rubyonrails-core