mautic

Mautic rails

RoR helper / wrapper for Mautic API and forms

Rails 6.0+ compatible Ruby 3.1+ compatible

Installation

Add this line to your application's Gemfile:

gem "mautic", "~> 3.1"

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

• In your mautic, create new

• Got to /your-mount-point/connections

• Create new connection - enter URL to your mautic

• 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

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

• 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: "[e-mail]"} )
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:

• 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

• 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.

• add concern to your controller

   include Mautic::ReceiveWebHooks
  

• 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.