enziinsystem / mautic-rails

Mautic ruby client / wrapper

Mautic rails

RoR helper / wrapper for Mautic API and forms

Rails 4.2.8+, 5.1+ compatible

Installation

Add this line to your application's Gemfile:

gem 'mautic', '~> 2.3'

And then execute:

$ bundle

Also you need migrate database:

$ rails db:migrate

Configuration

add to config/initializers/mautic.rb:

Mautic.configure do |config|
  # This is for oauth handshake token url. I need to know where your app listen
  config.base_url = "https://my-rails-app.com"
  # OR it can be Proc 
  # *optional* This is your default mautic URL - used in form helper 
  config.mautic_url = "https://mautic.my.app"
  # Set authorize condition for manage Mautic::Connections
  config.authorize_mautic_connections = ->(controller) { false }
end

Manage mautic connections

You can use builtin Mautic:ConnectionsController:

add to config/routes.rb

mount Mautic::Engine => "/mautic"

note: Make sure that you have some user authorization. There is builtin mechanism, in Mautic.config.authorize_mautic_connections = which return false to prevent all access by default (see: app/controllers/mautic/connections_controller.rb:3). For change this, you need add to config/initializers/mautic.rb:

Mautic.config.authorize_mautic_connections = ->(controller) { current_user.admin? }

OR use your own controller, by including concern

class MyOwnController < ApplicationController
  before_action :authorize_user

  include Mautic::ConnectionsControllerConcern
end

Concern require additional routes (authorize and oauth2) in routes.rb

resources :my_resources do
  member do
    get :authorize
    get :oauth2
  end
end

Create mautic connection

1. In your mautic, create new

2. Got to /your-mount-point/connections

3. Create new connection - enter URL to your mautic

4. Copy callback url then go to you mautic

   In mautic you need add API oauth2 login.

   http://localhost:3000/mautic/connections/:ID/oauth2
   

   ID = is your Mautic::Connection ID

5. Create new Oauth2 API connections. Use callback url from previous step and copy key and secret to form in your app

6. Update and use Authorize button for handshake

For example of integration check https://github.com/luk4s/redmine_mautic

Usage

Find connection which you want to use:

m = Mautic::Connection.last

Get specify contact:

contact = m.contact.find(1) # => #<Mautic::Contact id=1 ...>

Collections of contacts:

m.contacts.where(search: "gmail").each do |contact|
  #<Mautic::Contact id=12 ...>
  #<Mautic::Contact id=21 ...>
  #<Mautic::Contact id=99 ...>
end

New instance of contacts:

contact = m.contacts.new({ email: "[email protected]"} )
contact.save # => true

Update contact

contact.email = ""
contact.save # => false
contact.errors # => [{"code"=>400, "message"=>"email: This field is required.", "details"=>{"email"=>["This field is required."]}}]

Do not contact

contact.do_not_contact? # => false
contact.do_not_contact! message: "Some reason"
contact.do_not_contact? # => true

Remove do not contact

contact.do_not_contact? # => true
contact.remove_do_not_contact!
contact.do_not_contact? # => false

Campaigns

list of contacts campaigns (where contact is a member) and remove it from one

contact.campaigns #=> [Mautic::Campaign, ...]
campaign = contact.campaigns.find { |campaign| campaign.name == "Newsletter" }
campaign.remove_contact! contact.id

or add contact back

campaign = connection.campaigns.where(search: "Newsletter").first
campaign.add_contact! contact.id

Of course you can use more than contact: assets, emails, companies, forms, points ...

Gem provides simple Mautic form submit

There are two options of usage:

1. Use default mautic url from configuration and shortcut class method:

  # form: ID of form in Mautic *required*
  # url: Mautic URL - default is from configuration
  # request: request object (for domain, and forward IP...) *optional*
  Mautic::FormHelper.submit(form: "mautic form ID") do |i|
    i.form_field1 = "value1"
    i.form_field2 = "value2"
  end

2. Or create instance

# request is *optional*
m = Mautic::FormHelper.new("https://mymautic.com", request)
m.data = {} # hash of attributes
m.push # push data to mautic 

Webhook receiver

Receive webhook from mautic, parse it and prepare for use.

1. add concern to your controller

    include Mautic::ReceiveWebHooks
   

2. in routes must be specify :mautic_id, for example:

    post "webhook/:mautic_id", action: "webhook", on: :collection
   

Contributing

Ideas and pull requests are welcome!

License

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