Action Mailer 基礎 · Ruby on Rails 指南

# Action Mailer 基礎本文全面介紹如何在程序中收發郵件，Action Mailer 的內部機理，以及如何測試“郵件程序”（mailer）。讀完本文，你將學到： * 如何在 Rails 程序內收發郵件； * 如何生成及編輯 Action Mailer 類和郵件視圖； * 如何設置 Action Mailer； * 如何測試 Action Mailer 類； ### Chapters 1. [簡介](#%E7%AE%80%E4%BB%8B) 2. [發送郵件](#%E5%8F%91%E9%80%81%E9%82%AE%E4%BB%B6) * [生成郵件程序的步驟](#%E7%94%9F%E6%88%90%E9%82%AE%E4%BB%B6%E7%A8%8B%E5%BA%8F%E7%9A%84%E6%AD%A5%E9%AA%A4) * [自動編碼郵件頭](#%E8%87%AA%E5%8A%A8%E7%BC%96%E7%A0%81%E9%82%AE%E4%BB%B6%E5%A4%B4) * [Action Mailer 方法](#action-mailer-%E6%96%B9%E6%B3%95) * [郵件程序的視圖](#%E9%82%AE%E4%BB%B6%E7%A8%8B%E5%BA%8F%E7%9A%84%E8%A7%86%E5%9B%BE) * [Action Mailer 布局](#action-mailer-%E5%B8%83%E5%B1%80) * [在 Action Mailer 視圖中生成 URL](#%E5%9C%A8-action-mailer-%E8%A7%86%E5%9B%BE%E4%B8%AD%E7%94%9F%E6%88%90-url) * [發送多種格式郵件](#%E5%8F%91%E9%80%81%E5%A4%9A%E7%A7%8D%E6%A0%BC%E5%BC%8F%E9%82%AE%E4%BB%B6) * [發送郵件時動態設置發送選項](#%E5%8F%91%E9%80%81%E9%82%AE%E4%BB%B6%E6%97%B6%E5%8A%A8%E6%80%81%E8%AE%BE%E7%BD%AE%E5%8F%91%E9%80%81%E9%80%89%E9%A1%B9) * [不渲染模板](#%E4%B8%8D%E6%B8%B2%E6%9F%93%E6%A8%A1%E6%9D%BF) 3. [接收郵件](#%E6%8E%A5%E6%94%B6%E9%82%AE%E4%BB%B6) 4. [Action Mailer 回調](#action-mailer-%E5%9B%9E%E8%B0%83) 5. [使用 Action Mailer 幫助方法](#%E4%BD%BF%E7%94%A8-action-mailer-%E5%B8%AE%E5%8A%A9%E6%96%B9%E6%B3%95) 6. [設置 Action Mailer](#%E8%AE%BE%E7%BD%AE-action-mailer) * [Action Mailer 設置示例](#action-mailer-%E8%AE%BE%E7%BD%AE%E7%A4%BA%E4%BE%8B) * [設置 Action Mailer 使用 Gmail](#%E8%AE%BE%E7%BD%AE-action-mailer-%E4%BD%BF%E7%94%A8-gmail) 7. [測試郵件程序](#%E6%B5%8B%E8%AF%95%E9%82%AE%E4%BB%B6%E7%A8%8B%E5%BA%8F) 8. [攔截郵件](#%E6%8B%A6%E6%88%AA%E9%82%AE%E4%BB%B6) ### 1 簡介 Rails 使用 Action Mailer 實現發送郵件功能，郵件由郵件程序和視圖控制。郵件程序繼承自 `ActionMailer::Base`，作用和控制器類似，保存在文件夾 `app/mailers` 中，對應的視圖保存在文件夾 `app/views` 中。 ### 2 發送郵件本節詳細介紹如何創建郵件程序及對應的視圖。 #### 2.1 生成郵件程序的步驟 ##### 2.1.1 創建郵件程序 ``` $ rails generate mailer UserMailer create app/mailers/user_mailer.rb invoke erb create app/views/user_mailer invoke test_unit create test/mailers/user_mailer_test.rb ``` 如上所示，生成郵件程序的方法和使用其他生成器一樣。郵件程序在某種程度上就是控制器。執行上述命令后，生成了一個郵件程序，一個視圖文件夾和一個測試文件。如果不想使用生成器，可以手動在 `app/mailers` 文件夾中新建文件，但要確保繼承自 `ActionMailer::Base`： ``` class MyMailer < ActionMailer::Base end ``` ##### 2.1.2 編輯郵件程序郵件程序和控制器類似，也有稱為“動作”的方法，以及組織內容的視圖。控制器生成的內容，例如 HTML，發送給客戶端；郵件程序生成的消息則通過電子郵件發送。文件 `app/mailers/user_mailer.rb` 中有一個空的郵件程序： ``` class UserMailer < ActionMailer::Base default from: 'from@example.com' end ``` 下面我們定義一個名為 `welcome_email` 的方法，向用戶的注冊 Email 中發送一封郵件： ``` class UserMailer < ActionMailer::Base default from: 'notifications@example.com' def welcome_email(user) @user = user @url = 'http://example.com/login' mail(to: @user.email, subject: 'Welcome to My Awesome Site') end end ``` 簡單說明一下這段代碼。可用選項的詳細說明請參見“[Action Mailer 方法](#complete-list-of-action-mailer-methods)”一節。 * `default`：一個 Hash，該郵件程序發出郵件的默認設置。上例中我們把 `:from` 郵件頭設為一個值，這個類中的所有動作都會使用這個值，不過可在具體的動作中重設。 * `mail`：用于發送郵件的方法，我們傳入了 `:to` 和 `:subject` 郵件頭。和控制器一樣，動作中定義的實例變量可以在視圖中使用。 ##### 2.1.3 創建郵件程序的視圖在文件夾 `app/views/user_mailer/` 中新建文件 `welcome_email.html.erb`。這個視圖是郵件的模板，使用 HTML 編寫： ``` <!DOCTYPE html> <html> <head> <meta content='text/html; charset=UTF-8' http-equiv='Content-Type' /> </head> <body> <h1>Welcome to example.com, <%= @user.name %></h1> You have successfully signed up to example.com, your username is: <%= @user.login %>. To login to the site, just follow this link: <%= @url %>. Thanks for joining and have a great day! </body> </html> ``` 我們再創建一個純文本視圖。因為并不是所有客戶端都可以顯示 HTML 郵件，所以最好發送兩種格式。在文件夾 `app/views/user_mailer/` 中新建文件 `welcome_email.text.erb`，寫入以下代碼： ``` Welcome to example.com, <%= @user.name %> =============================================== You have successfully signed up to example.com, your username is: <%= @user.login %>. To login to the site, just follow this link: <%= @url %>. Thanks for joining and have a great day! ``` 調用 `mail` 方法后，Action Mailer 會檢測到這兩個模板（純文本和 HTML），自動生成一個類型為 `multipart/alternative` 的郵件。 ##### 2.1.4 調用郵件程序其實，郵件程序就是渲染視圖的另一種方式，只不過渲染的視圖不通過 HTTP 協議發送，而是通過 Email 協議發送。因此，應該由控制器調用郵件程序，在成功注冊用戶后給用戶發送一封郵件。過程相當簡單。首先，生成一個簡單的 `User` 腳手架： ``` $ rails generate scaffold user name email login $ rake db:migrate ``` 這樣就有一個可用的用戶模型了。我們需要編輯的是文件 `app/controllers/users_controller.rb`，修改 `create` 動作，成功保存用戶后調用 `UserMailer.welcome_email` 方法，向剛注冊的用戶發送郵件： ``` class UsersController < ApplicationController # POST /users # POST /users.json def create @user = User.new(params[:user]) respond_to do |format| if @user.save # Tell the UserMailer to send a welcome email after save UserMailer.welcome_email(@user).deliver format.html { redirect_to(@user, notice: 'User was successfully created.') } format.json { render json: @user, status: :created, location: @user } else format.html { render action: 'new' } format.json { render json: @user.errors, status: :unprocessable_entity } end end end end ``` `welcome_email` 方法返回 `Mail::Message` 對象，在其上調用 `deliver` 方法發送郵件。 #### 2.2 自動編碼郵件頭 Action Mailer 會自動編碼郵件頭和郵件主體中的多字節字符。更復雜的需求，例如使用其他字符集和自編碼文字，請參考 [Mail](https://github.com/mikel/mail) 庫的用法。 #### 2.3 Action Mailer 方法下面這三個方法是郵件程序中最重要的方法： * `headers`：設置郵件頭，可以指定一個由字段名和值組成的 Hash，或者使用 `headers[:field_name] = 'value'` 形式； * `attachments`：添加郵件的附件，例如，`attachments['file-name.jpg'] = File.read('file-name.jpg')`； * `mail`：發送郵件，傳入的值為 Hash 形式的郵件頭，`mail` 方法負責創建郵件內容，純文本或多種格式，取決于定義了哪種郵件模板； ##### 2.3.1 添加附件在 Action Mailer 中添加附件十分方便。 * 傳入文件名和內容，Action Mailer 和 [Mail](https://github.com/mikel/mail) gem 會自動猜測附件的 MIME 類型，設置編碼并創建附件。 ``` attachments['filename.jpg'] = File.read('/path/to/filename.jpg') ``` 觸發 `mail` 方法后，會發送一個由多部分組成的郵件，附件嵌套在類型為 `multipart/mixed` 的頂級結構中，其中第一部分的類型為 `multipart/alternative`，包含純文本和 HTML 格式的郵件內容。 Mail gem 會自動使用 Base64 編碼附件。如果想使用其他編碼方式，可以先編碼好，再把編碼后的附件通過 Hash 傳給 `attachments` 方法。 * 傳入文件名，指定郵件頭和內容，Action Mailer 和 Mail gem 會使用傳入的參數添加附件。 ``` encoded_content = SpecialEncode(File.read('/path/to/filename.jpg')) attachments['filename.jpg'] = {mime_type: 'application/x-gzip', encoding: 'SpecialEncoding', content: encoded_content } ``` 如果指定了 `encoding` 鍵，Mail 會認為附件已經編碼了，不會再使用 Base64 編碼附件。 ##### 2.3.2 使用行間附件在 Action Mailer 3.0 中使用行間附件比之前版本簡單得多。 * 首先，在 `attachments` 方法上調用 `inline` 方法，告訴 Mail 這是個行間附件： ``` def welcome attachments.inline['image.jpg'] = File.read('/path/to/image.jpg') end ``` * 在視圖中，可以直接使用 `attachments` 方法，將其視為一個 Hash，指定想要使用的附件，在其上調用 `url` 方法，再把結果傳給 `image_tag` 方法： ``` Hello there, this is our image <%= image_tag attachments['image.jpg'].url %> ``` * 因為我們只是簡單的調用了 `image_tag` 方法，所以和其他圖片一樣，在附件地址之后，還可以傳入選項 Hash： ``` Hello there, this is our image <%= image_tag attachments['image.jpg'].url, alt: 'My Photo', class: 'photos' %> ``` ##### 2.3.3 發給多個收件人要想把一封郵件發送給多個收件人，例如通知所有管理員有新用戶注冊網站，可以把 `:to` 鍵的值設為一組郵件地址。這一組郵件地址可以是一個數組；也可以是一個字符串，使用逗號分隔各個地址。 ``` class AdminMailer < ActionMailer::Base default to: Proc.new { Admin.pluck(:email) }, from: 'notification@example.com' def new_registration(user) @user = user mail(subject: "New User Signup: #{@user.email}") end end ``` 使用類似的方式還可添加抄送和密送，分別設置 `:cc` 和 `:bcc` 鍵即可。 ##### 2.3.4 在郵件中顯示名字有時希望收件人在郵件中看到自己的名字，而不只是郵件地址。實現這種需求的方法是把郵件地址寫成 `"Full Name <email>"` 格式。 ``` def welcome_email(user) @user = user email_with_name = "#{@user.name} <#{@user.email}>" mail(to: email_with_name, subject: 'Welcome to My Awesome Site') end ``` #### 2.4 郵件程序的視圖郵件程序的視圖保存在文件夾 `app/views/name_of_mailer_class` 中。郵件程序之所以知道使用哪個視圖，是因為視圖文件名和郵件程序的方法名一致。如前例，`welcome_email` 方法的 HTML 格式視圖是 `app/views/user_mailer/welcome_email.html.erb`，純文本格式視圖是 `welcome_email.text.erb`。要想修改動作使用的視圖，可以這么做： ``` class UserMailer < ActionMailer::Base default from: 'notifications@example.com' def welcome_email(user) @user = user @url = 'http://example.com/login' mail(to: @user.email, subject: 'Welcome to My Awesome Site', template_path: 'notifications', template_name: 'another') end end ``` 此時，郵件程序會在文件夾 `app/views/notifications` 中尋找名為 `another` 的視圖。`template_path` 的值可以是一個數組，按照順序查找視圖。如果想獲得更多靈活性，可以傳入一個代碼塊，渲染指定的模板，或者不使用模板，渲染行間代碼或純文本： ``` class UserMailer < ActionMailer::Base default from: 'notifications@example.com' def welcome_email(user) @user = user @url = 'http://example.com/login' mail(to: @user.email, subject: 'Welcome to My Awesome Site') do |format| format.html { render 'another_template' } format.text { render text: 'Render text' } end end end ``` 上述代碼會使用 `another_template.html.erb` 渲染 HTML，使用 `'Render text'` 渲染純文本。這里用到的 `render` 方法和控制器中的一樣，所以選項也都是一樣的，例如 `:text`、`:inline` 等。 #### 2.5 Action Mailer 布局和控制器一樣，郵件程序也可以使用布局。布局的名字必須和郵件程序類一樣，例如 `user_mailer.html.erb` 和 `user_mailer.text.erb` 會自動識別為郵件程序的布局。如果想使用其他布局文件，可以在郵件程序中調用 `layout` 方法： ``` class UserMailer < ActionMailer::Base layout 'awesome' # use awesome.(html|text).erb as the layout end ``` 還是跟控制器布局一樣，在郵件程序的布局中調用 `yield` 方法可以渲染視圖。在 `format` 代碼塊中可以把 `layout: 'layout_name'` 選項傳給 `render` 方法，指定使用其他布局： ``` class UserMailer < ActionMailer::Base def welcome_email(user) mail(to: user.email) do |format| format.html { render layout: 'my_layout' } format.text end end end ``` 上述代碼會使用文件 `my_layout.html.erb` 渲染 HTML 格式；如果文件 `user_mailer.text.erb` 存在，會用來渲染純文本格式。 #### 2.6 在 Action Mailer 視圖中生成 URL 和控制器不同，郵件程序不知道請求的上下文，因此要自己提供 `:host` 參數。一個程序的 `:host` 參數一般是相同的，可以在 `config/application.rb` 中做全局設置： ``` config.action_mailer.default_url_options = { host: 'example.com' } ``` ##### 2.6.1 使用 `url_for` 方法生成 URL 使用 `url_for` 方法時必須指定 `only_path: false` 選項，這樣才能確保生成絕對 URL，因為默認情況下如果不指定 `:host` 選項，`url_for` 幫助方法生成的是相對 URL。 ``` <%= url_for(controller: 'welcome', action: 'greeting', only_path: false) %> ``` 如果沒全局設置 `:host` 選項，使用 `url_for` 方法時一定要指定 `only_path: false` 選項。 ``` <%= url_for(host: 'example.com', controller: 'welcome', action: 'greeting') %> ``` 如果指定了 `:host` 選項，Rails 會生成絕對 URL，沒必要再指定 `only_path: false`。 ##### 2.6.2 使用具名路由生成 URL 郵件客戶端不能理解網頁中的上下文，沒有生成完整地址的基地址，所以使用具名路由幫助方法時一定要使用 `_url` 形式。如果沒有設置全局 `:host` 參數，一定要將其傳給 URL 幫助方法。 ``` <%= user_url(@user, host: 'example.com') %> ``` #### 2.7 發送多種格式郵件如果同一動作有多個模板，Action Mailer 會自動發送多種格式的郵件。例如前面的 `UserMailer`，如果在 `app/views/user_mailer` 文件夾中有 `welcome_email.text.erb` 和 `welcome_email.html.erb` 兩個模板，Action Mailer 會自動發送 HTML 和純文本格式的郵件。格式的順序由 `ActionMailer::Base.default` 方法的 `:parts_order` 參數決定。 #### 2.8 發送郵件時動態設置發送選項如果在發送郵件時想重設發送選項（例如，SMTP 密令），可以在郵件程序動作中使用 `delivery_method_options` 方法。 ``` class UserMailer < ActionMailer::Base def welcome_email(user, company) @user = user @url = user_url(@user) delivery_options = { user_name: company.smtp_user, password: company.smtp_password, address: company.smtp_host } mail(to: @user.email, subject: "Please see the Terms and Conditions attached", delivery_method_options: delivery_options) end end ``` #### 2.9 不渲染模板有時可能不想使用布局，直接使用字符串渲染郵件內容，可以使用 `:body` 選項。但別忘了指定 `:content_type` 選項，否則 Rails 會使用默認值 `text/plain`。 ``` class UserMailer < ActionMailer::Base def welcome_email(user, email_body) mail(to: user.email, body: email_body, content_type: "text/html", subject: "Already rendered!") end end ``` ### 3 接收郵件使用 Action Mailer 接收和解析郵件做些額外設置。接收郵件之前，要先設置系統，把郵件轉發給程序。所以，在 Rails 程序中接收郵件要完成以下步驟： * 在郵件程序中實現 `receive` 方法； * 設置郵件服務器，把郵件轉發到 `/path/to/app/bin/rails runner 'UserMailer.receive(STDIN.read)'`；在郵件程序中定義 `receive` 方法后，Action Mailer 會解析收到的郵件，生成郵件對象，解碼郵件內容，實例化一個郵件程序，把郵件對象傳給郵件程序的 `receive` 實例方法。下面舉個例子： ``` class UserMailer < ActionMailer::Base def receive(email) page = Page.find_by(address: email.to.first) page.emails.create( subject: email.subject, body: email.body ) if email.has_attachments? email.attachments.each do |attachment| page.attachments.create({ file: attachment, description: email.subject }) end end end end ``` ### 4 Action Mailer 回調在 Action Mailer 中也可設置 `before_action`、`after_action` 和 `around_action`。 * 和控制器中的回調一樣，可以傳入代碼塊，或者方法名的符號形式； * 在 `before_action` 中可以使用 `defaults` 和 `delivery_method_options` 方法，或者指定默認郵件頭和附件； * `after_action` 可以實現類似 `before_action` 的功能，而且在 `after_action` 中可以使用實例變量； ``` class UserMailer < ActionMailer::Base after_action :set_delivery_options, :prevent_delivery_to_guests, :set_business_headers def feedback_message(business, user) @business = business @user = user mail end def campaign_message(business, user) @business = business @user = user end private def set_delivery_options # You have access to the mail instance, # @business and @user instance variables here if @business && @business.has_smtp_settings? mail.delivery_method.settings.merge!(@business.smtp_settings) end end def prevent_delivery_to_guests if @user && @user.guest? mail.perform_deliveries = false end end def set_business_headers if @business headers["X-SMTPAPI-CATEGORY"] = @business.code end end end ``` * 如果在回調中把郵件主體設為 `nil` 之外的值，會阻止執行后續操作； ### 5 使用 Action Mailer 幫助方法 Action Mailer 繼承自 `AbstractController`，因此為控制器定義的幫助方法都可以在郵件程序中使用。 ### 6 設置 Action Mailer 下述設置選項最好在環境相關的文件（`environment.rb`，`production.rb` 等）中設置。 | 設置項 | 說明 | | --- | --- | | `logger` | 運行郵件程序時生成日志信息。設為 `nil` 禁用日志。可設為 Ruby 自帶的 `Logger` 或 `Log4r` 庫。 | | `smtp_settings` | 設置 `:smtp` 發送方式的詳情。 | | `sendmail_settings` | 設置 `:sendmail` 發送方式的詳情。 | | `raise_delivery_errors` | 如果郵件發送失敗，是否拋出異常。僅當外部郵件服務器設置為立即發送才有效。 | | `delivery_method` | 設置發送方式，可設為 `:smtp`（默認）、`:sendmail`、`:file` 和 `:test`。詳情參閱 [API 文檔](http://api.rubyonrails.org/classes/ActionMailer/Base.html)。 | | `perform_deliveries` | 調用 `deliver` 方法時是否真發送郵件。默認情況下會真的發送，但在功能測試中可以不發送。 | | `deliveries` | 把通過 Action Mailer 使用 `:test` 方式發送的郵件保存到一個數組中，協助單元測試和功能測試。 | | `default_options` | 為 `mail` 方法設置默認選項值（`:from`，`:reply_to` 等）。 | 完整的設置說明參見“設置 Rails 程序”一文中的“[設置 Action Mailer](configuring.html#configuring-action-mailer)”一節。 #### 6.1 Action Mailer 設置示例可以把下面的代碼添加到文件 `config/environments/$RAILS_ENV.rb` 中： ``` config.action_mailer.delivery_method = :sendmail # Defaults to: # config.action_mailer.sendmail_settings = { # location: '/usr/sbin/sendmail', # arguments: '-i -t' # } config.action_mailer.perform_deliveries = true config.action_mailer.raise_delivery_errors = true config.action_mailer.default_options = {from: 'no-reply@example.com'} ``` #### 6.2 設置 Action Mailer 使用 Gmail Action Mailer 現在使用 [Mail](https://github.com/mikel/mail) gem，針對 Gmail 的設置更簡單，把下面的代碼添加到文件 `config/environments/$RAILS_ENV.rb` 中即可： ``` config.action_mailer.delivery_method = :smtp config.action_mailer.smtp_settings = { address: 'smtp.gmail.com', port: 587, domain: 'example.com', user_name: '<username>', password: '<password>', authentication: 'plain', enable_starttls_auto: true } ``` ### 7 測試郵件程序郵件程序的測試參閱“[Rails 程序測試指南](%7B%7B%20site.baseurl%7D%7D%E3%80%81testing.html#testing-your-mailers)”。 ### 8 攔截郵件有時，在郵件發送之前需要做些修改。Action Mailer 提供了相應的鉤子，可以攔截每封郵件。你可以注冊一個攔截器，在交給發送程序之前修改郵件。 ``` class SandboxEmailInterceptor def self.delivering_email(message) message.to = ['sandbox@example.com'] end end ``` 使用攔截器之前要在 Action Mailer 框架中注冊，方法是在初始化腳本 `config/initializers/sandbox_email_interceptor.rb` 中添加以下代碼： ``` ActionMailer::Base.register_interceptor(SandboxEmailInterceptor) if Rails.env.staging? ``` 上述代碼中使用的是自定義環境，名為“staging”。這個環境和生產環境一樣，但只做測試之用。關于自定義環境的詳細介紹，參閱“[新建 Rails 環境](configuring.html#creating-rails-environments)”一節。 ### 反饋歡迎幫忙改善指南質量。如發現任何錯誤，歡迎修正。開始貢獻前，可先行閱讀[貢獻指南：文檔](http://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html#contributing-to-the-rails-documentation)。翻譯如有錯誤，深感抱歉，歡迎 [Fork](https://github.com/ruby-china/guides/fork) 修正，或至此處[回報](https://github.com/ruby-china/guides/issues/new)。文章可能有未完成或過時的內容。請先檢查 [Edge Guides](http://edgeguides.rubyonrails.org) 來確定問題在 master 是否已經修掉了。再上 master 補上缺少的文件。內容參考 [Ruby on Rails 指南準則](ruby_on_rails_guides_guidelines.html)來了解行文風格。最后，任何關于 Ruby on Rails 文檔的討論，歡迎到 [rubyonrails-docs 郵件群組](http://groups.google.com/group/rubyonrails-docs)。