Mail Service

From Ocean Framework Documentation Wiki
(Redirected from Mail - Sending Email)
Jump to: navigation, search

The Mail service sends email with guaranteed dispatch. The POST request used to send an email returns immediately, returning an AsyncJob which may be polled to check the progress of sending the email, or deleted to interrupt the job before it has started or after it has finished.

The use of an asynchronous job ensures that each email is sent, regardless of the volume of email and of any error states encountered. Exceptions will be handled and retries will be made accordingly.

Emails always have both an HTML version and a plaintext version. Both can be specified separately; if one is missing, it is computed from the other using Kramdown markup or intelligent HTML to plaintext conversion.

It is also possible to specify Text resources for both versions. Text substitutions can also be performed on the contents.


The Mail service manages the Email resource.

The Mail Resource
Sends an email with guaranteed dispatch.

Sending Email from the back end

Sending an email from a back end service is also done by creating a Mail Resource. There is a helper function provided by the ocean-rails gem, Api.send_mail:

 # Send an email asynchronously. The Mailer role is required.
 def self.send_mail(from: "nobody@#{BASE_DOMAIN}", to: nil, 
                    subject: nil, 
                    plaintext: nil, html: nil,
                    plaintext_url: nil, html_url: nil, substitutions: nil)
   Api.request "#{INTERNAL_OCEAN_API_URL}/v1/mails", :post, 
     x_api_token: Api.service_token,
     body: {
       from: from, to: to, subject: subject, 
       plaintext: plaintext, html: html,
       plaintext_url: plaintext_url, html_url: html_url, 
       substitutions: substitutions