عرض مصدر Rails/action mailer basics

= أساسيات إجراء المراسلة =
يوفّر لك هذا الدليل كل ما تحتاجه للبدء في إرسال واستقبال رسائل البريد الإلكتروني من وإلى تطبيقك، والعديد من عمليّات إجراء المراسلة (Action Mailer) الداخليّة. كما يغطي كيفية اختبار مُرسلي بريدك (mailers).

ستتعلم بعد قراءة هذا الدليل:
* كيفيّة إرسال واستقبال البريد الإلكتروني داخل تطبيق ريلز.
* كيفيّة إنشاء وتعديل صنف إجراء المراسلة والعرض المرتبط به.
* كيفيّة إعداد إجراء المراسلة لبيئتك.
* كيفيّة اختبار أصنافك لإجراء المراسلة.

== مقدمة ==
يسمح لك إجراء المراسلة (Action Mailer) بإرسال رسائل البريد الإلكتروني من تطبيقك باستخدام الأصناف <code>mailer</code> والعروض المرتبطة بها (views).

تعمل مُرسلات البريد بطريقة مشابهة جدًا لوحدات التحكّم. وهي ترث من <code>ActionMailer::Base</code> وتتوضع في app/mailers  ولديها عروض مرتبطة تظهر في app/views.

== إرسال البريد الإلكتروني ==
سيوفر هذا القسم دليلًا مُفصّلًا لإنشاء مُرسل بريد والعروض المرتبطة به.

=== خطوات إنشاء مرسل بريد إلكتروني ===

==== إنشاء المرسل ====
<syntaxhighlight lang="shell">
$ bin/rails generate mailer UserMailer
create  app/mailers/user_mailer.rb
create  app/mailers/application_mailer.rb
invoke  erb
create    app/views/user_mailer
create    app/views/layouts/mailer.text.erb
create    app/views/layouts/mailer.html.erb
invoke  test_unit
create    test/mailers/user_mailer_test.rb
create    test/mailers/previews/user_mailer_preview.rb
</syntaxhighlight><syntaxhighlight lang="shell">
# app/mailers/application_mailer.rb
class ApplicationMailer < ActionMailer::Base
  default from: "from@example.com"
  layout 'mailer'
end
 
# app/mailers/user_mailer.rb
class UserMailer < ApplicationMailer
end
</syntaxhighlight>كما ترى، يمكنك توليد مُرسلات بريد مثلما تستخدم المولّدات الأخرى مع ريلز. تتشابه مُرسلات البريد من الناحية النظرية مع وحدات التحكّم، ولذلك نحصل على مُرسل بريد ومجلّد للعروض واختبار.

إن لم ترغب في استخدام مولّد، يمكنك إنشاء ملفك الخاص داخل app/mailers لكن المهم أن تتأكّد أنّه يرث من <code>ActionMailer::Base</code>:<syntaxhighlight lang="rails">
class MyMailer < ActionMailer::Base
end
</syntaxhighlight>

==== تعديل المرسل ====
تشبه مُرسلات البريد الإلكتروني إلى حد بعيد وحدات تحكّم ريلز. لديها أيضا توابع تسمّى "إجراءات" (actions) وتستخدم العروض لهيكلة المحتوى. يُنشئ مرسلٌ رسالة للتسليم عبر البريد الإلكتروني عندما تُولّد وحدة التحكّم محتوى مثل [[HTML]] لإرساله مرة أخرى إلى العميل.

يحتوي app/mailers/user_mailer.rb على مُرسل بريد فارغ.<syntaxhighlight lang="rails">
class UserMailer < ApplicationMailer
end
</syntaxhighlight>فلنضف تابعًا باسم <code>welcome_email</code> يرسل بريدًا إلكترونيًا إلى عنوان البريد الإلكتروني المسجل للمستخدم:<syntaxhighlight lang="rails">
class UserMailer < ApplicationMailer
  default from: 'notifications@example.com'
 
  def welcome_email
    @user = params[:user]
    @url  = 'http://example.com/login'
    mail(to: @user.email, subject: 'Welcome to My Awesome Site')
  end
end
</syntaxhighlight>فيما يلي شرح سريع للعناصر المعروضة في التابع. للحصول على قائمة كاملة بجميع الخيارات المتاحة، يرجى إلقاء نظرة أدناه في قسم "قائمة خصائص إجراء المراسلة الكاملة القابلة للتعيين من طرف المستخدم".
* <code>default</code>: (كائن <code>[[Ruby/Hash|Hash]]</code>) يمثِّل جدول <code>[[Ruby/Hash|Hash]]</code> للقيم الافتراضية لأي بريد إلكتروني ترسله من هذا المُرسل. نُعيّن في هذه الحالة قيمة  الترويسة <code>from:</code> لجميع الرسائل في هذا الصنف. يمكن إعادة تعريف (override) هذا الحقل مع كل بريد إلكتروني على حدة.
* <code>mail</code>: رسالة البريد الإلكتروني الفعليّة التي نُمرّر الترويستين <code>to:</code> و <code>subject:</code> داخلها.
تصبح أي متغيّرات نسخة نعرّفها في التابع متاحة للاستخدام في العرض مثل حالة وحدات التحكم تمامًا.

==== إنشاء عرض لإجراء المراسلة ====
أنشئ ملفًا يسمّى welcome_email.html.erb في app/views/user_mailer/‎. سيُستخدم هذا القالب (template) للبريد الإلكتروني بتنسيق [[HTML]]:<syntaxhighlight lang="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>
    <p>
      You have successfully signed up to example.com,
      your username is: <%= @user.login %>.<br>
    </p>
    <p>
      To login to the site, just follow this link: <%= @url %>.
    </p>
    <p>Thanks for joining and have a great day!</p>
  </body>
</html>
</syntaxhighlight>لننشئ أيضًا جزءًا نصيًا لهذا البريد الإلكتروني. لا يفضّل كل العملاء رسائل إلكترونيّة بتنسيق [[HTML]]، وبالتالي إرسال كليهما هو أفضل الممارسات. أنشئ إذًا ملفًّا يسمّى welcome_email.text.erb في app/views/user_mailer/‎ :<syntaxhighlight lang="text">
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!

</syntaxhighlight>عند استدعاء التابع <code>mail</code> الآن، سيكتشف إجراء المراسلة قالبين (النص و HTML) ويُنشئ بريدًا إلكترونيًّا multipart/alternative تلقائيًا.

==== استدعاء المرسل ====
مُرسلات البريد هي في الواقع مجرد طريقة أخرى لتصيير (rendering) العرض. بدلًا من تصيير عرض وإرساله عبر بروتوكول HTTP، يُرسلونه ببساطة عبر بروتوكولات البريد الإلكتروني. ونتيجة لهذا، من المنطقي أن تطلب وحدة تحكّمك من مرسل رسائل البريد بإرسال بريد إلكتروني عند إنشاء مستخدم بنجاح.

ضبط هذه العملية بسيط للغاية.

فلننشئ أولًا، سقالة بسيطة (أي scaffold) باسم <code>User</code>:<syntaxhighlight lang="shell">
$ bin/rails generate scaffold user name email login
$ bin/rails db:migrate
</syntaxhighlight>لدينا الآن نموذج مُستخدم للتلاعب به. سنُعدّل فقط على الملف app/controllers/users_controller.rb بجعله يرشد <code>UserMailer</code> لإرسال بريد إلكتروني للمستخدم حديث الإنشاء عبر تعديل إجراء الإنشاء (create action) وإدخال نداء إلى <code>UserMailer.with(user: @user).welcome_email</code> مباشرةً بعد حفظ المستخدم بنجاح.

يتكامل إجراء المراسلة بشكل جيد مع الوظيفة الفعالة (Active Job)، لذا تتمكن من إرسال رسائل إلكترونيّة خارج دورة الطلب-الاستجابة، بحيث لا يضطر المستخدم إلى الانتظار:<syntaxhighlight lang="rails">
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.with(user: @user).welcome_email.deliver_later
 
        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
</syntaxhighlight>'''ملاحظة''': السلوك الافتراضي للوظيفة الفعالة (Active Job) هو تنفيذ المهام عبر المحوّل <code>async:</code>. لذا يمكنك استخدام <code>deliver_later</code> الآن لإرسال رسائل البريد الإلكتروني بشكل غير متزامن. يُشغّل محوّل الوظيفة الفعالة الافتراضي المهام مع مجمع خيوط قيد المعالجة. وهو مناسب تمامًا لبيئات التطوير/الاختبار، نظرًا لأنَّه لا يتطلب أي بنية تحتيّة خارجيّة ولكنه غير ملائم للإنتاج بما أنّه يزيل الوظائف المعلّقة عند إعادة التشغيل. إن كنت في حاجة إلى خلفيّة دائمة (persistent backend)، فستحتاج لاستخدام محوّل وظيفة فعالة (Active Job adapter) يحوي خلفيّة دائمة (Sidekiq ،Resque، إلخ).

إن رغبت في إرسال بريد إلكتروني على الفور (من cronjob على سبيل المثال) فقط استدعي <code>deliver_now</code>:<syntaxhighlight lang="rails">
class SendWeeklySummary
  def run
    User.find_each do |user|
      UserMailer.with(user: user).weekly_summary.deliver_now
    end
  end
end
</syntaxhighlight>أي زوج قيم مفتاح مُمرّر إلى <code>with</code> يصبح <code>params</code> لإجراء المراسلة (mailer action). لذلك، يجعل

<code>with(user: @user, account: @user.account)‎</code> المعاملين <code>params[:user]‎</code> و <code>params[:account]‎</code> متوفّرين في إجراء المراسلة.

ويعيد التابع <code>welcome_email</code> كائنًا من النوع <code>ActionMailer::MessageDelivery</code> والذي يمكن إخباره لاحقًا بالإرسال الأن عبر <code>deliver_now</code> أو الإرسال لاحقًا عبر <code>deliver_later</code> لإرسال نفسه. الكائن <code>ActionMailer::MessageDelivery</code> هو مجرد غلاف (wrapper) حول <code>Mail::Message</code>. إن رغبت في فحص أو تغيير أو فعل بأي شيء آخر مع الكائن <code>Mail::Message</code>، تستطيع الوصول إليه عبر التابع <code>message</code> في الكائن <code>ActionMailer::MessageDelivery</code>.

=== التشفير التلقائي لقيم الترويسة ===
يعالج إجراء المراسلة الترميز التلقائي لأحرف متعددة البايت داخل الترويسات وجسم الرسالة.

لأمثلة أكثر تعقيدًا مثل تعريف مجموعات أحرف بديلة أو ترميز النص ذاتيًّا أولًا، الرجاء الرجوع إلى المكتبة [https://github.com/mikel/mail Mail].

=== قائمة توابع إجراء المراسلة الكاملة ===
تحتاج ثلاثة توابع فقط لأي رسالة بريد إلكتروني:
* <code>headers</code> - يحدّد أي ترويسة بريد تريدها. تستطيع تمرير [[Ruby/Hash|جدول Hash]] بأسماء حقول وأزواج القيم أو يمكنك استدعاءه بالشكل <code>headers[:field_name]‎ = 'value'‎</code>.

* <code>attachments</code> - يسمح لك بإضافة مرفقات إلى بريدك الإلكتروني مثل <code>attachments['file-name.jpg'] = File.read('file-name.jpg')‎</code>.

* <code>mail</code> - يرسل البريد الإلكتروني الفعلي ذاته. تستطيع تمرير ترويسة [[Ruby/Hash|كجدول Hash]] إلى التابع <code>mail</code> كمعاملة، ثم يُنشئ التابع  بريدًا إلكترونيَّا، إما كنص عادي أو نص متعدّد الأجزاء، اعتمادًا على قوالب البريد الإلكتروني التي عرّفتها.

==== إضافة المرفقات ====
يُسهّل إجراء المراسلة إضافة المرفقات.
* مرّر اسم الملف والمحتوى وسيخمّن إجراء المراسلة و[https://github.com/mikel/mail جوهرة البريد] (Mail gem) تلقائيًا النوع MIME، ويضبط التشفير وينشئ المُرفق.
<syntaxhighlight lang="rails">
attachments['filename.jpg'] = File.read('/path/to/filename.jpg')
</syntaxhighlight>عندما ينفَّذ التابع <code>mail</code>، سيُرسل بريد إلكتروني متعدد الأجزاء مع مُرفق، مُضمّن بشكل مناسب مع كون المستوى الأعلى <code>multipart/mixed</code> والجزء الأول عبارة عن <code>multipart/alternative</code> يحتوي على النص العادي ورسائل بريد إلكتروني بتنسيق [[HTML]].

'''ملاحظة''': سيُشفّر البريد المُرفق تلقائيا بتشفير Base64. إن أردت شيئًا مختلفًا شفّر مُحتواك ومرّره المحتوى المشفّر وترميزه داخل [[Ruby/Hash|جدول Hash]] إلى التابع <code>attachments</code>.
* مرّر اسم الملف وحدد الترويسة والمحتوى وسيستخدم إجراء المراسلة و <code>mail</code> الإعدادات التي تمررها.
<syntaxhighlight lang="rails">
encoded_content = SpecialEncode(File.read('/path/to/filename.jpg'))
attachments['filename.jpg'] = {
  mime_type: 'application/gzip',
  encoding: 'SpecialEncoding',
  content: encoded_content
}
</syntaxhighlight>'''ملاحظة''': يفترض البريد أنَّ محتواك مُشفّر مسبقًا ولا يحاول تشفيره عبر Base64.

==== إنشاء مرفقات مضمّنة (Making Inline Attachments) ====
يجعل إجراء المراسلة 3.0 المُرفقات المضمّنة - والتي تطلّبت الكثير من التلاعب في الإصدارات قبل 3.0 - بالبساطة والسهولة كما يجدر بها أن تكون.
* أولًا لتأمر mail يتحويل مُرفق إلى مُرفق مضمّن (Inline Attachment) عليك فقط استدعاء <code>inline.</code> مع تابع المرفقات داخل مُرسلك (Mailer):
<syntaxhighlight lang="rails">
def welcome
  attachments.inline['image.jpg'] = File.read('/path/to/image.jpg')
end
</syntaxhighlight>
* ثم تستطيع في عرضك أن تشير (reference) إلى <code>attachments</code> [[Ruby/Hash|كجدول Hash]] وتحدد المُرفق الذي تريد إظهاره، وتستدعي <code>url</code> عليه ثم تمرر النتيجة إلى التابع <code>image_tag</code>:
<syntaxhighlight lang="html">
<p>Hello there, this is our image</p>
 
<%= image_tag attachments['image.jpg'].url %>
</syntaxhighlight>
* نظرًا لأن هذا استدعاء اعتيادي إلى <code>image_tag</code>، تستطيع تمرير [[Ruby/Hash|جدول Hash]] من الخيارات بعد عنوان URL المُرفق كما هو الحال مع أي صورة أخرى:
<syntaxhighlight lang="html">
<p>Hello there, this is our image</p>
 
<%= image_tag attachments['image.jpg'].url, alt: 'My Photo', class: 'photos' %>
</syntaxhighlight>

==== إرسال بريد إلكتروني إلى عدة مستلمين ====
من الممكن إرسال بريد إلى مستلم واحد أو أكثر في بريد إلكتروني واحد (مثلًا إعلام كافة المسؤولين بتسجيل جديد) عن طريق تعيين قائمة بعناوين البريد إلى المفتاح <code>to:</code>. يمكن أن تكون قائمة عناوين البريد مصفوفة من عناوين البريد أو سلسلة واحدة مع عناوين مفصولة بفواصل.<syntaxhighlight lang="rails">
class AdminMailer < ApplicationMailer
  default to: -> { Admin.pluck(:email) },
          from: 'notification@example.com'
 
  def new_registration(user)
    @user = user
    mail(subject: "New User Signup: #{@user.email}")
  end
end
</syntaxhighlight>يمكن استخدام نفس التنسيق لوضع نسخة كربونية (:Cc) ونسخة كربونية مخفية (:Bcc) باستخدام المفتاحين <code>cc:</code> و <code>bcc:</code> على التوالي.

==== إرسال البريد الإلكتروني بالاسم ====
قد ترغب في بعض الأحيان في إظهار اسم الشخص بدلًا عن مجرّد عنوان بريده الإلكتروني عندما يستلم البريد الإلكتروني الذي أرسلته إليه. وطريقة عمل ذلك هي بتنسيق عنوان البريد الإلكتروني بالشكل ‎<code>"Full Name" <email>‎</code>.<syntaxhighlight lang="rails">
def welcome_email
  @user = params[:user]
  email_with_name = %("#{@user.name}" <#{@user.email}>)
  mail(to: email_with_name, subject: 'Welcome to My Awesome Site')
end
</syntaxhighlight>

=== عروض المرسل (Mailer Views) ===
تُوجد عروض المُرسل (Mailer) في المُجلّد app/views/name_of_mailer_class. يعرف الصنف عرض مرسل البريد المحدّد تلقائيًّا لأنَّ اسمه مماثل لتابع المُرسل. في المثال الوارد أعلاه، سيكون عرض مُرسل بريدنا للتابع <code>welcome_email</code> هو app/views/user_mailer/welcome_email.html.erb بالنسبة للنسخة [[HTML]] و welcome_email.text.erb لنسخة النص العادي.

لتغيير عرض المُرسل الافتراضي لإجرائك (action)،نفّذ ما يلي:<syntaxhighlight lang="rails">
class UserMailer < ApplicationMailer
  default from: 'notifications@example.com'
 
  def welcome_email
    @user = params[:user]
    @url  = 'http://example.com/login'
    mail(to: @user.email,
         subject: 'Welcome to My Awesome Site',
         template_path: 'notifications',
         template_name: 'another')
  end
end
</syntaxhighlight>سيبحث في هذه الحالة عن قوالب في app/views/notifications بالاسم <code>another</code>. تستطيع أيضًا تحديد مصفوفة مسارات لـ <code>template_path</code> وسيُبحث بها حسب الترتيب.

إن أردت مزيدًا من المرونة، تستطيع أيضًا تمرير كتلة (block) وتصيير (render) قوالب محددّة أو حتى تصيير على نفس السطر أو تصيير نص دون استخدام ملف قالب:<syntaxhighlight lang="rails">
class UserMailer < ApplicationMailer
  default from: 'notifications@example.com'
 
  def welcome_email
    @user = params[: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 plain: 'Render text' }
    end
  end
end
</syntaxhighlight>سيُصيّر هذا القالب "another_template.html.erb" لجزء [[HTML]] ويستخدم النص المُصيّر للجزء النصّي.

أمر التصيير (render) هو نفسه المُستخدم داخل [[Rails/action controller overview|وحدة التحكم]] (Action Controller) كي تستطيع استخدام جميع الخيارات نفسها مثل <code>text:</code> و <code>inline:</code> ...إلخ.

==== التخزين المؤقت لعرض المرسل ====
تستطيع تخزين الأجزاء مؤقّتًّا (fragment caching) في عروض المُرسل مثلما نفعل مع عروض التطبيق باستخدام التابع <code>cache</code>.<syntaxhighlight lang="html">
<% cache do %>
  <%= @company.name %>
<% end %>
</syntaxhighlight>ولاستخدام هذه الخاصيّة، تحتاج لإعداد تطبيقك بالشكل التالي:<syntaxhighlight lang="rails">
config.action_mailer.perform_caching = true
</syntaxhighlight>يُدعم التخزين المؤقت للأجزاء أيضًا في رسائل البريد متعدّدة الأجزاء. اقرأ المزيد حول التخزين المؤقت في [[Rails/caching with rails|دليل التخزين المؤقت]] في ريلز.

=== تخطيطات إجراء المراسلة ===
يملك مُرسل البريد تخطيطات تمامًا مثل عروض وحدات التحكّم. يجب أن يكون اسم التخطيط نفس اسم مُرسلك مثل user_mailer.html.erb و user_mailer.text.erb كي يُتعرّف عليه تلقائيًا كتخطيط من طرف مُرسلك.

استدعي التابع <code>layout</code> كي تستخدم ملفًّا مختلفًا في مُرسلك:<syntaxhighlight lang="rails">
class UserMailer < ApplicationMailer
  layout 'awesome' # use awesome.(html|text).erb as the layout
end
</syntaxhighlight>استخدم <code>yield</code> لتصيير العرض داخل التخطيط مثل طرق العرض لوحدات التحكّم تمامًا.

تستطيع أيضًا تمرير الخيار <code>'layout: 'layout_name</code> لاستدعاء التصيير داخل بُنية التنسيق لتحديد مخططات مختلفة للتنسيقات المختلفة:<syntaxhighlight lang="rails">
class UserMailer < ApplicationMailer
  def welcome_email
    mail(to: params[:user].email) do |format|
      format.html { render layout: 'my_layout' }
      format.text
    end
  end
end
</syntaxhighlight>سيُعرض جزء HTML باستخدام الملف my_layout.html.erb وجزء النص مع ملف user_mailer.text.erb المعتاد في حالة وجوده.

=== معاينة رسائل البريد الإلكتروني (Previewing Emails) ===
توفر معاينات إجراء المراسلة طريقة لمعرفة كيفيّة ظهور الرسائل الإلكترونية من خلال زيارة عنوان URL خاص يعرضها. يجب تسمية صنف معاينة <code>UserMailer</code> في المثال أعلاه <code>UserMailerPreview</code> ووضعه في test/mailers/previews/user_mailer_preview.rb. لمشاهدة معاينة <code>welcome_email</code>، عرّف استخدام تابع له نفس الاسم واستدعي <code>UserMailer.welcome_email</code>:<syntaxhighlight lang="rails">
class UserMailerPreview < ActionMailer::Preview
  def welcome_email
    UserMailer.with(user: User.first).welcome_email
  end
end
</syntaxhighlight>ثم ستُصبح المعاينة متاحة في http://localhost:3000/rails/mailers/user_mailer/welcome_email. 

سيُعاد التحميل تلقائيًا إن غيّرت شيئًا ما في app/views/user_mailer/welcome_email.html.erb أو المُرسل نفسه حتى تتمكن من رؤية التنسيق الجديد على الفور. تتوفّر أيضًا قائمة بالمعاينات في http://localhost:3000/rails/mailers.

توجد أصناف المعاينة هذه في test/mailers/previews. يمكن إعدادها باستخدام الخيار <code>preview_path</code>. إن أردت مثلًا تغييرها إلى lib/mailer_previews تستطيع إعداد في config/application.rb:<syntaxhighlight lang="rails">
config.action_mailer.preview_path = "#{Rails.root}/lib/mailer_previews"
</syntaxhighlight>

=== توليد العناوين URL في عروض إجراء المراسلة ===
لا تحتوي نسخة البريد على أي سياق حول الطلب الوارد عكس وحدات التحكّم، لذا عليك تقديم المعامل <code>host:</code> بنفسك.

نظرًا لأنه عادةً ما يكون <code>host:</code> متسقًا عبر التطبيق، تستطيع إعداده على العموم (globally) في config/application.rb:<syntaxhighlight lang="rails">
config.action_mailer.default_url_options = { host: 'example.com' }
</syntaxhighlight>لا تستطيع استخدام أي من المساعدين <code>path_*</code> داخل البريد الإلكتروني بسبب هذا السلوك. سوف تحتاج بدلًا من ذلك إلى استخدام المساعد <code>url_*</code>. مثلًا بدل استخدام:<syntaxhighlight lang="html">
<%= link_to 'welcome', welcome_path %>
</syntaxhighlight>ستحتاج لاستخدام:<syntaxhighlight lang="html">
<%= link_to 'welcome', welcome_url %>
</syntaxhighlight>ستعمل الروابط الآن في رسائلك الإلكترونية باستخدام العنوان URL الكامل.

==== إنشاء عناوين URL مع <code>url_for</code> ====
ينشئ <code>url_for</code> عنوان URL كامل افتراضيًا في القوالب.

إن لم تضبط الخيار <code>host:</code> على المستوى العام، تأكّد من تمريره إلى <code>url_for</code>.<syntaxhighlight lang="html">
<%= url_for(host: 'example.com',
            controller: 'welcome',
            action: 'greeting') %>
</syntaxhighlight>

==== إنشاء عناوين URL باستخدام المسارات المسماة ====
لا يمتلك عملاء البريد الإلكتروني أي سياق ويب وبالتالي لا تحتوي المسارات على عنوان URL أساسي لتكوين عناوين ويب كاملة. لذلك يجب دائمًا استخدام المتغيّر "url_" لمساعدي المسارات الموجهة المُسمّاة.

إن لم تضبط الخيار <code>host:</code> على المستوى العام، فتأكّد من تمريره إلى المساعد <code>url</code>.<syntaxhighlight lang="html">
<%= user_url(@user, host: 'example.com') %>
</syntaxhighlight>'''ملاحظة''': تتطلب الروابط غير GET استخدام [https://github.com/rails/rails/blob/master/actionview/app/assets/javascripts rails-ujs] أو [https://github.com/rails/jquery-ujs jQuery UJS] ولن تعمل في قوالب المُرسل (mailer templates). سيؤدي ذلك إلى طلبات GET العادية.

=== إضافة الصور في عروض إجراء المراسلة ===
لا تحتوي نسخة البريد على أي سياق حول الطلب الوارد عكس وحدات التحكّم، لذا عليك تقديم المعامل <code>asset_host:</code> بنفسك.

نظرًا لكون <code>asset_host:</code> عادةً متسقًا عبر التطبيق، تستطيع إعداده بشكل عام (globally) في config/application.rb:<syntaxhighlight lang="rails">
config.action_mailer.asset_host = 'http://example.com'
</syntaxhighlight>تستطيع الآن عرض صورة داخل رسالتك الإلكترونيّة.<syntaxhighlight lang="html">
<%= image_tag 'image.jpg' %>
</syntaxhighlight>

=== إرسال رسائل متعددة الأجزاء ===
سيُرسل إجراء المراسلة رسائل إلكترونيّة متعددة الأجزاء تلقائيًا إن كان لديك قوالب مختلفة لنفس الإجراء (action). لذلك، سيُسرسل إجراء المراسلة تلقائيًا رسالة إلكترونيّة متعدّدة الأجزاء مع نسختين نصيّة و HTML مُعدّتين كجزئين مختلفين بالنسبة لمثالنا <code>UserMailer</code> إن كان الملف welcome_email.text.erb والملف welcome_email.html.erb موجودين في app/views/user_mailer.

يُحدّد <code>parts_order:</code> ترتيب الأجزاء التي تُدخَل داخل التابع <code>ActionMailer::Base.default</code>.

=== إرسال البريد الإلكتروني مع خيارات التسليم الديناميكي (Dynamic Delivery Options) ===
إن رغبت في إعادة تعريف (override) خيارات التسليم الافتراضيّة (مثل بيانات اعتماد SMTP) أثناء تسليم البريد الإلكتروني، تستطيع القيام بذلك باستخدام <code>delivery_method_options</code> في الإجراء <code>mailer</code>.<syntaxhighlight lang="rails">
class UserMailer < ApplicationMailer
  def welcome_email
    @user = params[:user]
    @url  = user_url(@user)
    delivery_options = { user_name: params[:company].smtp_user,
                         password: params[:company].smtp_password,
                         address: params[:company].smtp_host }
    mail(to: @user.email,
         subject: "Please see the Terms and Conditions attached",
         delivery_method_options: delivery_options)
  end
end
</syntaxhighlight>

=== إرسال رسائل البريد الإلكتروني دون تصيير القالب ===
قد توجد حالات تريد فيها تخطّي خطوة تصيير القالب وتزويد نص البريد الإلكتروني كسلسلة نصيّة. يمكنك تحقيق ذلك باستخدام الخيار <code>body:</code>. لا تنسَ في مثل هذه الحالات إضافة الخيار <code>content_type:</code>. وإلّا سوف يفترض ريلز انّ نوعه text/plain افتراضيّا.<syntaxhighlight lang="rails">
class UserMailer < ApplicationMailer
  def welcome_email
    mail(to: params[:user].email,
         body: params[:email_body],
         content_type: "text/html",
         subject: "Already rendered!")
  end
end
</syntaxhighlight>

== استلام رسائل البريد الإلكتروني ==
يمكن أن يكون تلقي رسائل البريد الإلكتروني وتحليلها باستخدام إجراء المراسلة معقّدًا نوعًا ما. عليك إعداد نظامك لتوجيه رسائل البريد إلى تطبيقك بطريقة ما، قبل وصول بريد إلكتروني إلى تطبيقك ريلز، والذي يحتاج للاستماع كي يتحقّق. لذلك لتلقي رسائل البريد الإلكتروني في تطبيق ريلز ستحتاج إلى:
* تعريف استخدام التابع <code>receive</code> في مُرسل بريدك.
* إعداد خادم بريدك الإلكتروني لإعادة توجيه الرسائل من العنوان (أو العناوين) الذي تريد استلام رسائل البريد الإلكتروني إلى <code>‎/path/to/app/bin/rails runner 'UserMailer.receive(STDIN.read)'</code>‎ .
يُحلّل (parse) إجراء المراسلة البريد الإلكتروني الوارد الخام بمجرّد تعريف التابع المُسمّى <code>receive</code> جاعلًا منه كائن بريد إلكتروني، ثم يفك ترميزه، وينشئ نسخة مُرسل بريد جديدة، ويُمرّر كائن البريد الإلكتروني إلى تابع نُسخة المُرسل <code>receive</code>. إليك مثال على ذلك:<syntaxhighlight lang="rails">
class UserMailer < ApplicationMailer
  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
</syntaxhighlight>

== ردود نداء إجراء المراسلة ==
يتيح لك إجراء المراسلة تحديد <code>before_action</code> و <code>after_action</code> و <code>around_action</code>.
* يمكن تحديد الفلاتر ببُنية أو رمز لتابع في صنف مرسل البريد بشكل شبيه بوحدات التحكّم.
* تستطيع استخدام <code>before_action</code> لتعبئة كائن البريد افتراضيًا أو <code>delivery_method_options</code> أو إدراج ترويسات ومرفقات افتراضية.
<syntaxhighlight lang="rails">
class InvitationsMailer < ApplicationMailer
  before_action { @inviter, @invitee = params[:inviter], params[:invitee] }
  before_action { @account = params[:inviter].account }
 
  default to:       -> { @invitee.email_address },
          from:     -> { common_address(@inviter) },
          reply_to: -> { @inviter.email_address_with_name }
 
  def account_invitation
    mail subject: "#{@inviter.name} invited you to their Basecamp (#{@account.name})"
  end
 
  def project_invitation
    @project    = params[:project]
    @summarizer = ProjectInvitationSummarizer.new(@project.bucket)
 
    mail subject: "#{@inviter.name.familiar} added you to a project in Basecamp (#{@account.name})"
  end
end
</syntaxhighlight>
* تستطيع استخدام <code>after_action</code> لتنفيذ إعداد مشابه كإجراء سابق <code>before_action</code> ولكن باستخدام متغيّرات نسخة (instance variables) مضبوطة بإجراء مُرسل بريدك (mailer action).
<syntaxhighlight lang="rails">

class UserMailer < ApplicationMailer
  before_action { @business, @user = params[:business], params[:user] }
 
  after_action :set_delivery_options,
               :prevent_delivery_to_guests,
               :set_business_headers
 
  def feedback_message
  end
 
  def campaign_message
  end
 
  private
 
    def set_delivery_options
      # mail لديك الوصول إلى النسخة,
      # @business و @user ومتغيرات النسخة
      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
</syntaxhighlight>
* تقوم مرشحات إجراء المراسلة بإحباط المعالجة الإضافيّة إن ضبط جسم الرسالة إلى قيمة غير معدومة (non-nil).

== استخدام مساعدي مُرسل الأفعال إجراء المراسلة ==
يرث إجراء المراسلة الآن من AbstractController، لذلك لديك حق الوصول إلى نفس المُساعدات العاديّة كما تفعل في Action Controller.

== إعداد مُرسل البريد ==
من الأفضل وضع خيارات التكوين التالية في أحد ملفات البيئة (environment.rb ،production.rb، إلخ ...)
{| class="wikitable"
|الإعداد
|الوصف
|-
|logger
|يولّد معلومات حول الدورة البريديّة (mailing run) إن توفّرت. يمكن ضبطه على nil كي لا يُسجّل أي شيء. يتوافق مع كل من مُسجّل روبي Logger والمسجّلات Log4r.
|-
|smtp_settings
|يسمح بالإعداد المُفصّل لتابع التسليم smtp:
* address: - يسمح لك باستخدام خادم بريد عن بعد. كل ما عليك هو تغييره عن إعداده "localhost" الافتراضي.
* port: - تستطيع في حالة عدم عمل خادم بريدك على المنفذ 25 تغييره.
* domain: - تستطيع إن إحتجت لتحديد نطاق HELO فعل ذلك هنا.
* user_name: - إن تطلّب خادم بريدك الإستيثاق عيّن اسم مستخدم في هذا الإعداد.
* password: - إن تطلّب خادم بريدك الإستيثاق عيّن كلمة المرور في هذا الإعداد.
* authentication: - إن تطلّب خادم بريدك الإستيثاق ستحتاج إلى تحديد نوعه في هذا الإعداد. هذا رمز وواحد من plain: (يرسل كلمة المرور بشكل واضح) و login: (سيرسل كلمة المرور المشفّرة على Base64) أو cram_md5: (يجمع آلية تحدّي/استجابة لتبادل المعلومات وخوارزميّة Message Digest 5 المُشفّرة لتجزئة المعلومات المهمّة)
* enable_starttls_auto: - يكتشف ما إن فُعّل STARTTLS في خادمك SMTP ويبدأ في استخدامه. إفتراضيّاً true.
* openssl_verify_mode: - عند استخدام TLS تستطيع ضبط كيفيّة تحقّق OpenSSL من الشهادة. يكون هذا مفيدًا حقًا إن إحتجت للتحقّق من صحّة شهادة ذاتيّة التوقيع و/أو بطاقة بدل (wildcard certificate). تستطيع استخدام اسم OpenSSL للتحقق من الثابت ('none' أو 'peer') أو مباشرة من الثابت ( OpenSSL::SSL::VERIFY_NONE أو OpenSSL::SSL::VERIFY_PEER)
|-
|sendmail_settings
|يسمح لك بإعادة تعريف خيارات تابع التسليم sendmail:
* location: - موقع ملف sendmail التنفيذي (executable). إفتراضيًّا هي /usr/sbin/sendmail .
* arguments: - مُتغيّرات سطر الأوامر التي ستُمرّر إلى sendmail. إفتراضيًّا -i.
|-
|raise_delivery_errors
|ما إن وجب رفع الأخطاء أم لا إن لم يُسلّم البريد الإلكتروني. يعمل هذا الإعداد فقط إن أُعدّ خادم البريد الإلكتروني الخارجي للتسليم الفوري.
|-
|delivery_method
|يُعرّف تابع تسليم. القيم المحتملة هي:
* smtp: (افتراضي) يمكن إعداده باستخدام config.action_mailer.smtp_settings
* sendmail: يمكن إعداده باستخدام config.action_mailer.sendmail_settings.
* file: حفظ رسائل البريد الإلكتروني بملفّات. يمكن إعداده باستخدام config.action_mailer.file_settings.
* test: حفظ رسائل البريد الإلكتروني في ActionMailer::Base.deliveries
راجع توثيقات API لمزيد من المعلومات.
|-
|perform_deliveries
|يحدّد إن نُفّذت عمليات التسليم فعلًا عند مُناداة التابع deliver على رسالة البريد. ذلك هو الوضع إفتراضيًّا ولكن يمكن إيقاف تشغيله للمساعدة في الاختبار الوظيفي.
|-
|deliveries
|يحافظ على مصفوفة من جميع الرسائل المرسلة عبر إجراء المراسلة  مع delivery_method :test. مفيدة خاصّة بلاختبار الوحدوي والوظيفي.
|-
|default_options
|تسمح لك بتعيين القيم الافتراضية لخيارات التابع mail (مثل from: و reply_to: وما إلى ذلك).
|}
للحصول على معلومات كاملة عن الإعدادات المحتملة راجع توثيق إعداد إجراء المراسلة في دليلنا إعداد تطبيقات ريلز.

== مثال لإعداد إجراء المراسلة ==
مثال على ذلك هو إضافة ما يلي بملفك config/environments/$RAILS_ENV.rb المناسب:
{| class="wikitable"
|config.action_mailer.delivery_method = :sendmail

<nowiki>#</nowiki> Defaults to:

<nowiki>#</nowiki> config.action_mailer.sendmail_settings = {

<nowiki>#</nowiki>   location: '/usr/sbin/sendmail',

<nowiki>#</nowiki>   arguments: '-i'

<nowiki>#</nowiki> }

config.action_mailer.perform_deliveries = true

config.action_mailer.raise_delivery_errors = true

config.action_mailer.default_options = {from: 'no-reply@example.com'}
|}

=== إعداد إجراء المراسلة لـ Gmail ===
بما أن إجراء المراسلة يستخدم الآن جوهرة البريد تصبح العمليّة ببساطة الإضافة إلى ملفكconfig/environments/$RAILS_ENV.rb:
{| class="wikitable"
|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 }
|}
ملاحظة: اعتبارًا من 15 تموز 2014 عمدت Google إلى زيادة إجراءاتها الأمنيّة وتحظر الآن محاولات التطبيقات التي تراها أقل أمانًا. تستطيع تغيير إعدادات حسابك Gmail هنا للسماح بالمحاولات. إن كانت المصادقة الثنائيةمُفعّلة  بحسابك Gmail ستحتاج لتعيين كلمة مرور تطبيق واستخدامها بدلاً من كلمة مرورك العاديّة. أو تستطيع بدلاً من ذلك استخدام ESP آخر لإرسال البريد الإلكتروني عن طريق استبدال "smtp.gmail.com" أعلاه بعنوان موفّرك.

== اختبار مُرسل البريد (Mailer Testing) ==
تستطيع إيجاد تعليمات مفصّلة حول كيفيّة اختبار مُرسلي بريدك في دليل الاختبار.

== اعتراض رسائل البريد الإلكتروني ==
هناك حالات تحتاج فيها لتعديل بريد إلكتروني قبل تسليمه. لحسن الحظ يوفّر إجراء المراسلة خطافًا لاعتراض كل بريد إلكتروني. تستطيع تسجيل مُعترض لإجراء تعديلات على رسائل البريد قبل تسليمها لوكلاء التوصيل مباشرة.
{| class="wikitable"
|class SandboxEmailInterceptor

 def self.delivering_email(message)

   message.to = ['sandbox@example.com']

 end

end
|}
يجب تسجيل المُعترض في إطار عمل إجراء المراسلة قبل أن يتمكن من القيام بواجبه. يمكنك ذلك في ملف تهيئة (initializer) من config/initializers/sandbox_email_interceptor.rb
{| class="wikitable"
|if ريلز.env.staging?

 ActionMailer::Base.register_interceptor(SandboxEmailInterceptor)

end
|}
يستخدم المثال أعلاه بيئة مخصصّة تسمى "التدريج" لاختبار خادم شبيه بخادم الإنتاج ولكن لأغراض الاختبار. تستطيع قراءة إنشاء بيئات ريلز لمزيد من المعلومات حول بيئات ريلز المخصصّة.

== مصدر ==
* صفحة إجراء المراسلة بتوثيق ريلز