Enveloop Ruby

Hello! 👋 enveloop-ruby is a Ruby wrapper for the Enveloop API. It simplifies configuring and sending messages (email & SMS/text) via Enveloop inside your Ruby and Ruby on Rails apps.

What is Enveloop?

Enveloop is a developer-focused message builder and API that makes it easy to design & send beautiful emails and texts from your app using a simple implementation. You can sign up for free and be up and running in a couple of minutes!

Installing the Enveloop Ruby Gem

There are a couple of ways to get started. Using RubyGems, you can install it locally with the following command:

gem install enveloop

Additionally, you can add the following to your application's Gemfile:

gem 'enveloop'

After doing so, you can run the following terminal command:

bundle install

Using the Enveloop Gem

The Enveloop Gem includes helpful methods to interact with the Enveloop API, including:

• send_message
• template_info

We'll talk about how to use some of these methods in the notes to follow.

Ruby (direct usage)

First, let's set up a connection. You'll need to require the enveloop gem, define a client, and add in your Enveloop API token. Your API token is located in the Settings for each project you have on Enveloop.

require 'enveloop'

enveloop = Enveloop::Client.new(api_key:`ENVELOOP_API_TOKEN')

Now that your connection is established, let's use a method to send a message.

(Note: This method call assumes that you have created a basic template in Enveloop and provides an example of a template variable you may use. Please alter according to how you have set up your template.)

Send an email message using an Enveloop template:

enveloop.send_message(
  template: 'welcome-email',
  to: 'user@email.com',
  from: 'welcome@myapp.com',
  subject: 'Welcome to My App!',
  template_variables: {
    first_name: 'John',
  }
)

Send an email message passing custom HTML

If you want to send a message, via Enveloop, and not use an Enveloop template, you can remove the template argument from the method and include the html argument instead (it takes a custom HTML body and creates a structured email message to send out).

enveloop.send_message(
  html: '<h1>Hello John, Welcome to MyApp</h1>',
  to: 'user@email.com',
  from: 'welcome@myapp.com',
  subject: 'Welcome to MyApp',
)

Send a text/SMS message

enveloop.send_message(
   template: 'registration-complete',
   to: '+14155551212',
   from: '+12056113369',
   template_variables: {
      first_name: 'Paul'
   }
)

(As you can see, the structure of the send_message method is similar, but we simply swap out an email address for a mobile number. Also, the template used is an SMS template on the Enveloop platform.)

Get information about a template (variables and body HTML):

enveloop.template_info(template: 'welcome-email')

Ruby on Rails

Using Enveloop with Ruby on Rails is easy as well. Here is a recommended approach for getting it set up in your Rails application.

Update your initializer

Add/update the following lines in your respective Rails environments file.

# remember to never include production keys in files you check into repos.

ENV['ENVELOOP_API_KEY'] = 'ENVELOOP_API_KEY'

config.action_mailer.delivery_method = :enveloop

config.action_mailer.enveloop_settings = { 
  api_key: ENV['ENVELOOP_API_TOKEN']
}

Create an Enveloop Mailer

From your command line, use a Rails generator to create a new Enveloop Mailer.

rails generate mailer EnveloopMailer

Modify your Enveloop Mailer

Now that the mailer is created, you can modify it and add in a custom method, based on your application, to call the send_message method in the Enveloop API.

class EnveloopMailer < ActionMailer::Base

   include Rails.application.routes.url_helpers 

   def new_comment_email(recipient, comment)
      enveloop.send_message(
         template: 'new-comment',
         to: recipient,
         from: 'hello@myapp.com',
         subject: subject,
         template_variables:{
            account_url: 'https://myapp.com',
            user_comment: comment
         }
      )
   end

   private

   def enveloop
      @enveloop ||= Enveloop::Client.new(api_key: ENV['ENVELOOP_API_KEY']) 
   end

end

Sending a message in your Rails app

Now, all that is left is to make a call to send a message, via Enveloop, whenever you need it.

EnveloopMailer.new_comment_email(@comment.user_email_address, @comment.body).deliver_now

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/enveloophq/enveloop-ruby.

This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Enveloop project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.