This repository contains the official Ruby wrapper for the Mailjet API, bootstraped with Mailjetter.
Check out all the resources and Ruby code examples in the Offical Documentation.
- Compatibility
- Installation
- Authentication
- Make your first call
- Call configuration specifics
- List of resources
- Request examples
- Send emails with ActionMailer
- Track email delivery
- Testing
- Contribute
This library requires Ruby v2.2.X.
The Rails ActionMailer integration is designed for Rails >= 5.
Use the below command to install the wrapper.
$ gem install mailjetAdd the following in your Gemfile:
# Gemfile
gem 'mailjet'If you wish to use the most recent release from Github, add the following in your Gemfile instead:
#Gemfile
gem 'mailjet', :git => 'https://github.com/mailjet/mailjet-gem.git'Then let the bundler magic happen:
$ bundle installThe Mailjet Email API uses your API and Secret keys for authentication. Grab and save your Mailjet API credentials by adding them to an initializer:
# initializers/mailjet.rb
Mailjet.configure do |config|
config.api_key = 'your-api-key'
config.secret_key = 'your-secret-key'
config.default_from = '[email protected]'
enddefault_from is optional if you send emails with :mailjet's SMTP.
But if you are using Mailjet with Rails, you can simply generate it:
$ rails generate mailjet:initializerHere's an example on how to send an email:
require 'mailjet'
Mailjet.configure do |config|
config.api_key = ENV['MJ_APIKEY_PUBLIC']
config.secret_key = ENV['MJ_APIKEY_PRIVATE']
config.api_version = "v3.1"
end
variable = Mailjet::Send.create(messages: [{
'From'=> {
'Email'=> '$SENDER_EMAIL',
'Name'=> 'Me'
},
'To'=> [
{
'Email'=> '$RECIPIENT_EMAIL',
'Name'=> 'You'
}
],
'Subject'=> 'My first Mailjet Email!',
'TextPart'=> 'Greetings from Mailjet!',
'HTMLPart'=> '<h3>Dear passenger 1, welcome to <a href=\'https://www.mailjet.com/\'>Mailjet</a>!</h3><br />May the delivery force be with you!'
}]
)
p variable.attributes[:messages]The Mailjet API is spread among three distinct versions:
v3- The Email APIv3.1- Email Send API v3.1, which is the latest version of our Send APIv4- SMS API (not supported in this library yet)
Since most Email API endpoints are located under v3, it is set as the default one and does not need to be specified when making your request. For the others you need to specify the version using api_version. For example, if using Send API v3.1:
require 'mailjet'
Mailjet.configure do |config|
config.api_key = ENV['MJ_APIKEY_PUBLIC']
config.secret_key = ENV['MJ_APIKEY_PRIVATE']
config.api_version = "v3.1"
endThe default base domain name for the Mailjet API is https://api.mailjet.com. You can modify this base URL by setting a value for end_point in your call:
Mailjet.configure do |config|
config.api_key = ENV['MJ_APIKEY_PUBLIC']
config.secret_key = ENV['MJ_APIKEY_PRIVATE']
config.api_version = "v3.1"
config.end_point = "https://api.us.mailjet.com"
endIf your account has been moved to Mailjet's US architecture, the URL value you need to set is https://api.us.mailjet.com.
You can find the list of all available resources for this library, as well as their configuration, in /lib/mailjet/resources.
- Class names' first letter is capitalized followed by the rest of the resource name in lowercase (e.g.
listrecipientwill beListrecipientin ruby) - Ruby attribute names are the underscored versions of API attributes names (e.g.
IsActivewill beis_activein ruby)
Use the create method of the Mailjet CLient (i.e. variable = Mailjet::$resource.create($params)).
$params will be a list of properties used in the request payload.
# Create a new contact:
require 'mailjet'
Mailjet.configure do |config|
config.api_key = ENV['MJ_APIKEY_PUBLIC']
config.secret_key = ENV['MJ_APIKEY_PRIVATE']
end
variable = Mailjet::Contact.create(email: "[email protected]"
)
p variable.attributes['Data']Some APIs allow the use of action endpoints. To use them in this wrapper, the API endpoint is in the beginning, followed by an underscore, followed by the action you are performing - e.g. Contact_managecontactslists.
Use id to specify the ID you want to apply a POST request to (used in case of action on a resource).
# Manage the subscription status of a contact to multiple lists
require 'mailjet'
Mailjet.configure do |config|
config.api_key = ENV['MJ_APIKEY_PUBLIC']
config.secret_key = ENV['MJ_APIKEY_PRIVATE']
end
variable = Mailjet::Contact_managecontactslists.create(id: $ID, contacts_lists: [{
'ListID'=> '$ListID_1',
'Action'=> 'addnoforce'
}, {
'ListID'=> '$ListID_2',
'Action'=> 'addforce'
}]
)
p variable.attributes['Data']Use the .all method of the Mailjet CLient (i.e. Mailjet::$resource.all()) to retrieve all objects you are looking for. By default, .all will retrieve only 10 objects - you have to specify limit: 0 if you want to GET them all (up to 1000 objects).
> recipients = Mailjet::Listrecipient.all(limit: 0)You can refine queries using API filters, as well as the following parameters:
format::json,:xml,:rawxml,:html,:csvor:phpserialized(default::json)limit: integer (default:10)offset: integer (default:0)sort:[[:property, :asc], [:property, :desc]]
# To retrieve all contacts from contact list ID 123:
> variable = Mailjet::Contact.all(limit: 0, contacts_list: 123)Use the .find method to retrieve a specific object. Specify the ID of the object inside the parentheses.
# Retrieve a specific contact ID.
require 'mailjet'
Mailjet.configure do |config|
config.api_key = ENV['MJ_APIKEY_PUBLIC']
config.secret_key = ENV['MJ_APIKEY_PRIVATE']
end
variable = Mailjet::Contact.find($CONTACT_EMAIL)
p variable.attributes['Data']> Mailjet::Contact.count
=> 83> Mailjet::Contact.first
=> #<Mailjet::Contact>A PUT request in the Mailjet API will work as a PATCH request - the update will affect only the specified properties. The other properties of an existing resource will neither be modified, nor deleted. It also means that all non-mandatory properties can be omitted from your payload.
Here's an example of a PUT request:
> recipient = Mailjet::Listrecipient.first
=> #<Mailjet::Listrecipient>
> recipient.is_active = false
=> false
> recipient.attributes
=> {...} # attributes hash
> recipient.save
=> true
> recipient.update_attributes(is_active: true)
=> trueHere's an example of a DELETE request:
> recipient = Mailjet::Listrecipient.first
=> #<Mailjet::Listrecipient>
> recipient.delete
> Mailjet::Listrecipient.delete(123)
=> #<Mailjet::Listrecipient>Upon a successful DELETE request the response will not include a response body, but only a 204 No Content response code.
A quick walkthrough to use Rails Action Mailer here.
First set your delivery method (here Mailjet SMTP relay servers):
# application.rb or config/environments specific settings, which take precedence
config.action_mailer.delivery_method = :mailjetOr if you prefer sending messages through Mailjet Send API:
# application.rb
config.action_mailer.delivery_method = :mailjet_apiYou can use Mailjet specific options with delivery_method_options as detailed in the official ActionMailer doc:
class AwesomeMailer < ApplicationMailer
def awesome_mail(user)
mail(
to: user.email,
delivery_method_options: { api_key: 'your-api-key', secret_key: 'your-secret-key' }
)
end
endKeep in mind that to use the latest version of the Send API, you need to specify the version via delivery_method_options:
delivery_method_options: { version: 'v3.1' }Other supported options are:
# For v3_1 API
* :api_key
* :secret_key
* :'Priority'
* :'CustomCampaign'
* :'DeduplicateCampaign'
* :'TemplateLanguage'
* :'TemplateErrorReporting'
* :'TemplateErrorDeliver'
* :'TemplateID'
* :'TrackOpens'
* :'TrackClicks'
* :'CustomID'
* :'EventPayload'
* :'Variables'
* :'Headers'
# For v3_0 API
* :recipients
* :'mj-prio'
* :'mj-campaign'
* :'mj-deduplicatecampaign'
* :'mj-templatelanguage'
* :'mj-templateerrorreporting'
* :'mj-templateerrordeliver'
* :'mj-templateid'
* :'mj-trackopen'
* :'mj-trackclick',
* :'mj-customid'
* :'mj-eventpayload'
* :vars
* :headersOtherwise, you can pass the custom Mailjet SMTP headers directly:
headers['X-MJ-CustomID'] = 'rubyPR_Test_ID_1469790724'
headers['X-MJ-EventPayload'] = 'rubyPR_Test_Payload'
headers['X-MJ-TemplateLanguage'] = 'true'Creating a Mailer:
$ 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.rbIn the UserMailer class you can set up your email method:
#app/mailers/user_mailer.rb
class UserMailer < ApplicationMailer
def welcome_email()
mail(from: "[email protected]", to: "[email protected]",
subject: "This is a nice welcome email")
end
endNext, create your templates in the views folder:
#app/views/user_mailer/welcome_email.html.erb
Hello world in HTML!
#app/views/user_mailer/welcome_email.text.erb
Hello world in plain text!There's also the ability to set Mailjet custom headers
#app/mailers/user_mailer.rb
class UserMailer < ApplicationMailer
def welcome_email()
headers['X-MJ-CustomID'] = 'custom value'
headers['X-MJ-EventPayload'] = 'custom payload'
mail(
from: "[email protected]",
to: "[email protected]",
subject: "This is a nice welcome email"
)
end
endFor sending email, you can call the method:
# In this example, we are sending the email immediately
UserMailer.welcome_email.deliver_now!For more information on ActionMailer::MessageDelivery, see the documentation HERE
Create the CSV content in a format compatible with the Mailjet API, see the documentation HERE
Mailjet::ContactslistCsv.send_data(ID_CONTACTLIST, File.open('some_csvdata.csv', 'r'))Mailjet::ContactPii.delete(contact_ID)You can setup your Rack application in order to receive feedback on emails you sent (clicks, etc.)
First notify Mailjet of your desired endpoint (say: 'http://www.my_domain.com/mailjet/callback') at https://www.mailjet.com/account/triggers
Then configure Mailjet's Rack application to catch these callbacks.
A typical Rails/ActiveRecord installation would look like that:
# application.rb
config.middleware.use Mailjet::Rack::Endpoint, '/mailjet/callback' do |params| # using the same URL you just set in Mailjet's administration
email = params['email'].presence || params['original_address'] # original_address is for typofix events
if user = User.find_by_email(email)
user.process_email_callback(params)
else
Rails.logger.fatal "[Mailjet] User not found: #{email} -- DUMP #{params.inspect}"
end
end
# user.rb
class User < ActiveRecord::Base
def process_email_callback(params)
# Returned events and options are described at https://eu.mailjet.com/docs/event_tracking
case params['event']
when 'open'
# Mailjet's invisible pixel was downloaded: user allowed for images to be seen
when 'click'
# a link (tracked by Mailjet) was clicked
when 'bounce'
# is user's email valid? Recipient not found
when 'spam'
# gateway or user flagged you
when 'blocked'
# gateway or user blocked you
when 'typofix'
# email routed from params['original_address'] to params['new_address']
else
Rails.logger.fatal "[Mailjet] Unknown event #{params['event']} for User #{self.inspect} -- DUMP #{params.inspect}"
end
endNote that since it's a Rack application, any Ruby Rack framework (say: Sinatra, Padrino, etc.) is compatible.
For maximum reliability, the gem is tested against Mailjet's server for some parts, which means that valid credentials are needed. Do NOT use your production account (create a new one if needed), because some tests are destructive.
# GEM_ROOT/config.yml
mailjet:
api_key: YOUR_API_KEY
secret_key: YOUR_SECRET_KEY
default_from: YOUR_REGISTERED_SENDER_EMAIL # the email you used to create the account should do itThen at the root of the gem, simply run:
bundle
bundle exec rakeMailjet loves developers. You can be part of this project!
This wrapper is a great introduction to the open source world, check out the code!
Feel free to ask anything, and contribute:
- Fork the project.
- Create a new branch.
- Implement your feature or bug fix.
- Add documentation for it.
- Add specs for your feature or bug fix.
- Commit and push your changes.
- Submit a pull request. Please do not include changes to the gemspec, or version file.
If you have suggestions on how to improve the guides, please submit an issue in our Official API Documentation repo.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent