Nowadays it is quite difficult to imagine any large service without email campaigns. How many emails with words "do-not-reply" does a user receive every day? Notifications about updates and different events, newsletters, holiday greetings to subscribers, promotional email offers - all these require a good dedicated service that can cope with current volumes of information. If you are looking for convenient and easy to use email automation tool, you will be interested to know about SendWithUs service. In this article, we will share some practical guides for using this service with a special focus on integration with Ruby on Rails apps.

The SendWithUs is a layer between the application and the service for sending emails. All email templates are stored on the service, they support versioning and A/B testing. Sending emails from application is performed by calling API functions. SendWithUs provides the official API-client libraries for integration with the main modern Web development technologies. Including Ruby on Rails, e.g. Sendwithus Ruby Action Mailer and Sendwithus Ruby Client.

Let’s look at an example of creating and sending a message from RoR-based application.

SendWithUs templates editor

At first, we have to create an email template on SendWithUs. With static text and markup everything is simple. For dynamic variables - Jinja template engine is supported.

An example of welcome email:

The editor is convenient, you can instantly see the resulting email with all styles. There is an opportunity to view an email with replacing data from Lorem ipsum, with manual input or JSON-object input.

The simple template is ready. In the upper right corner there is a unique identifier of a template, we will use it in our Rails application. The variables are passed to the template by the JSON-parameter in the API call. In this case, the expected structure is:

"user": { "name":"John", "created_at":"07/07/17" }

We will prepare it in our application.

Using the sendwithus_ruby_action_mailer gem

First of all, you have to install this Sendwithus Ruby gem and configure your application developer key in Rails initializer. It is worth to say that SendWithUs provides a handy opportunity to generate the keys for testing, including those which will allow sending all emails to the specified address without a chance to deliver an accidental test email to the user.

Let's take a look at a short example of the email initialization:

class SendWithUs::Notifier < SendWithUsMailer::Base

  def welcome(user)
    assign(:user, { name: user.name, created_at: user.created_at })

    mail(
      # version_name: 'New Version',
      # tags: [array, of, tags], #Tags are passes as categories to your email server
      # headers: { "X-HEADER-ONE": "header-value" },
      # cc: [{ address: 'cc@swuexample.com' }],
      # bcc: [{ address: 'bcc@swuexample.com' }],
      # locale:  'en-US',
      # files: [{id: 'image.png', data: Base64.encode64(‘file_data’)}],

      email_id: 'tem_XpniNepFNFHA2hw4n32MQB',
      reply_to: 'support@swuexample.com',
      from_name: 'Support',
      from_address: 'support@swuexample.com',
      recipient_name: user.name,
      recipient_address: user.email,
    )
  end
end

The assign method adds a pair "key - value" to the JSON data object, that is sent to the email template on SendWithUs. Other options are transferred to the mail method. Recipient_address and email_id are mandatory here.

Such attributes as from_name, from_address and reply_to, when being passed to the mail method, may have a default value. These values ​​can be set in several places. Here they are in order of priority:

1. In the context of the class: default from_address: 'support@swuexample.com'
2. In the settings for each template.
3. In the global email settings on SendWithUs.

The syntax of sending an email is similar to ActionMailer:

SendWithUs::Notifier.welcome(user).deliver

When we call the deliver method, a request is sent to the SendWithUs server with JSON parameters.

As you could notice, the cc and bcc parameters are the arrays of electronic addresses. However, recipient_address is a single-value parameter which takes only one recipient. It causes the problem of inability to send email with several addresses in the To field. If your application allows to send such emails, you will face the necessity to handle this situation by yourself. For example, only the first recipient is passed in the recipient_address parameter, the rest - in the cc.

The interface of SendWithUs allows setting PreHeaders - short pieces of information that appears after the subject lines in the inbox. They are used to provide a brief summary of email message. If this text is not defined, the email-clients will take first N characters from the message body and put them in this line. N depends on the client. Usually it is about 100 characters.

Marketing emails

SendWithUs can create email marketing campaigns. For this purpose, the Segment service is used where you can set the events that initiate sending an email from the campaign. To implement this, new users are created on SendWithUs every time when a new address appears in the recipient_address field. It is also possible to manage the users' data via API or WEB-interface. The set of parameters for each user can be extended, which will allow creating email marketing campaigns for the customers grouped by certain rules.

Why do we need it

If any changes are made to the email templates stored on SendWithUs' server, there is no need to redeploy the application. Simply creating a new version of the email and applying the changes will suffice. However, it is important to note that if the email requires a different set of data, the application must be able to prepare this data. In such cases, creating a new version of the application is necessary.

SendWithUs provides statistics for each template and generates diagrams based on various data points such as email opens, clicks on links within the email, and more. While the data set may not differ significantly from other statistics services, it is nonetheless useful.

With SendWithUs, the process of sending emails is greatly simplified. Users can simply open the service, select the required functions, and press a button. This eliminates the need to understand how to start an application, navigate the complexities of the console, or involve developers every time an email needs to be edited, as SendWithUs takes care of all of these tasks.

Final notes

We used SendWithUs in our work, we (as well as our customers) enjoyed its benefits, such as flexibility, ease of setting up and optimization and we believe that it is one of the best solutions for email automation. We hope this tutorial was useful and that you learned enough about SendWithUs to make you want to learn more and integrate it in your apps.