Mailgun-Ruby Snippets

This page is filled with snippets that cover almost every API endpoint and action. Copy, Paste, Go! There will be little inline documentation in these samples, please consult Mailgun’s official documentation for detailed information.

If you haven’t already installed the SDK, go to the README and follow the installation instructions.

These snippets require that you pipe in a few parameters. “mg_client” is instantiated like so:

require 'mailgun'
mg_client = Mailgun::Client.new "your-api-key"

Messages:

---

*Send a basic message: *

data = {:from => 'bob@sending_domain.com',
                  :to => 'sally@example.com',
                  :subject => 'The Ruby SDK is awesome!',
                  :text => 'It is really easy to send a message!'}

mg_client.send_message "sending_domain.com", data

Send a multipart text/html message:

data = {:from => 'bob@sending_domain.com',
                  :to => 'sally@example.com',
                  :subject => 'The Ruby SDK is awesome!',
                  :text => 'This is the text part.',
                  :html =&gt; '<p>This is the HTML part.</p>'}

mg_client.send_message "sending_domain.com", data

Send a custom MIME message:

# Don't include a file, pull the file to a string
mime_string = 'From: Bob Sample 
MIME-Version: 1.0
Content-Type: multipart/mixed;
boundary="--boundary-goes-here--"

Your Multipart MIME body

--boundary-goes-here--
Content-Type: text/plain

This is the text part of your message.

--boundary-goes-here--'

# The envelope recipient is defined here, as well as your MIME string
data = {:to => 'sally@example.com', :message => mime_string}

mg_client.send_message "sending_domain.com", data

Build a message, part by part, with Message Builder:

mb_obj = Mailgun::MessageBuilder.new

mb_obj.set_from_address "sender@example.com", {'first' => 'Sending', 'last' => 'User'}
mb_obj.add_recipient :to, "recipient@example.com", {'first' => 'Recipient', 'last' => 'User'}
mb_obj.set_subject "This is the subject!"
mb_obj.set_text_body "This is the text body."

mg_client.send_message "sending_domain.com", mb_obj

Build a message with attachments, part by part, with Message Builder:

mb_obj = Mailgun::MessageBuilder.new

mb_obj.set_from_address "sender@example.com", {'first' => 'Sending', 'last' => 'User'}
mb_obj.add_recipient :to, "recipient@example.com", {'first' => 'Recipient', 'last' => 'User'}
mb_obj.set_subject "This is the subject!"
mb_obj.set_text_body "This is the text body."

# Add separate attachments
mb_obj.add_attachment "/path/to/file/invoice_8675309.pdf", "Order Invoice - 8675309.pdf"
mb_obj.add_attachment "/path/to/file/datasheet_00001.pdf", "Product Datasheet - 00001.pdf"

# Attach inline image to message
mb_obj.add_inline_image "/path/to/file/product_image_00001.png"

mg_client.send_message "sending_domain.com", mb_obj

Send batches of 1000 messages per post:

bm_obj = Mailgun::BatchMessage.new

# Build message using Message Builder
bm_obj.set_from_address "sender@example.com", {'first' => 'Sending', 'last' => 'User'}
bm_obj.set_message_id("<20141014000000.11111.11111@example.com>") # optional
bm_obj.set_subject "This is the subject!"
bm_obj.set_text_body "This is the text body."

# Loop and add unlimited recipients (batch jobs will fire when thresholds reached)
bm_obj.add_recipient :to, "a_user@example.com"

# All message IDs returned in finalize method return
message_ids = bm_obj.finalize

Domains:

---

Get a list of all domains:

result = mg_client.get "domains", {:limit => 5, :skip => 0}

Get a single domain:

result = mg_client.get "domains/#{domain}"

Add a domain:

result = mg_client.post "domains", {:name => 'anothersample.mailgun.org',
                                     :smtp_password => 'super_secret',
                                     :spam_action => 'tag'}

*Delete a Domain: *

result = mg_client.delete "domains/#{domain}"

Unsubscribes:

---

*Get List of Unsubscribes: *

result = mg_client.get "#{domain}/unsubscribes", {:limit => 50, :skip => 10}

*Get Single Unsubscribe: *

result = mg_client.get "#{domain}/unsubscribes/#{email_address}"

*Unsubscribe a Recipient: *

result = mg_client.post "#{domain}/unsubscribes", {:address => 'bob@example.com', :tag => 'mypromotion'}

*Unsubscribe from all messages for a domain: *

result = mg_client.post "#{domain}/unsubscribes", {:address => 'bob@example.com', :tag => '*'}

*Remove an unsubscribe: *

result = mg_client.delete "#{domain}/unsubscribes/#{email_address}"

Complaints:

---

*Get List of Complaints: *

result = mg_client.get "#{domain}/complaints", {:limit => 50, :skip => 10}

*Get a Single Complaint: *

result = mg_client.get "#{domain}/complaints/#{email_address}"

*Create a complaint: *

result = mg_client.post "#{domain}/complaint", {:address => 'bob@example.com'}

*Remove a complaint: *

result = mg_client.delete "#{domain}/complaint/#{email_address}"

Bounces:

---

*Get List of Bounces: *

result = mg_client.get "#{domain}/bounces", {:limit => 50, :skip => 10}

*Get a Single Bounce Event: *

result = mg_client.get "#{domain}/bounces/#{email_address}"

*Create a Bounce: *

result = mg_client.post "#{domain}/bounces", {:address => 'bob@example.com',
                                               :code => 550,
                                               :error => 'Mailbox does not exist.'}

*Remove a Bounced Address: *

result = mg_client.delete "#{domain}/bounces/#{email_address}"

Statistics:

---

*Get Statistics: *

result = mg_client.get "#{domain}/stats", {:limit => 50,
                                            :skip => 10,
                                            :event => 'sent',
                                            "start-date" => 'Mon, 13 Feb 2015 00:00:00 GMT'}

*Remove a Tag: *

result = mg_client.delete "#{domain}/tags/#{tag}"

Events:

---

*Get Event: *

result = mg_client.get "#{domain}/events", {:event => 'rejected'}

Routes:

---

*Get List of Routes: *

result = mg_client.get "routes", {:limit => 50, :skip => 10}

*Get a Single Route by ID: *

result = mg_client.get "routes/#{route_id}"

*Create a Route: *

result = mg_client.post "routes",  {:priority => 10,
                                     :description => 'This is a test route',
                                     :expression => 'match_recipient(".*@gmail.com")',
                                     :action => 'forward("alice@example.com")'}

*Update a Route: *

result = mg_client.put "routes/#{route_id}",  {:priority => 10,
                                                :description => 'This is a test route',
                                                :expression => 'match_recipient(".*@gmail.com")',
                                                :action => 'forward("alice@example.com")'}

*Remove a Route: *

result = mg_client.delete "routes/#{route_id}"

Campaigns:

---

*Get List of Campaigns: *

result = mg_client.get "#{domain}/campaigns", {:limit => 50, :skip => 10}

*Get a Single Campaign: *

result = mg_client.get "#{domain}/campaigns/#{campaign_id}"

*Create a Campaign: *

result = mg_client.post "#{domain}/campaigns", {:name => 'My Campaign',
                                                 :id => 'campaign_123_2014'}

*Update a Campaign: *

result = mg_client.put "#{domain}/campaigns/#{campaign_id}", {:name => 'My Campaign',
                                                               :id => 'campaign_123_2014'}

*Remove a Campaign: *

result = mg_client.delete "#{domain}/campaigns/#{campaign_id}"

*Get Campaign Events: *

result = mg_client.get "#{domain}/campaigns/#{campaign_id}/events", {:event => 'clicked',
                                                                      :recipient => 'test@example.com',
                                                                      :country => 'US',
                                                                      :region => 'TX',
                                                                      :limit => 100,
                                                                      :page => 1,
                                                                      :count => true}

*Get a Single Campaign’s Stats: *

result = mg_client.get "#{domain}/campaigns/#{campaign_id}/stats", {:groupby => 'domain'}

*Get a Single Campaign’s Click Stats: *

result = mg_client.get "#{domain}/campaigns/#{campaign_id}/clicks", {:groupby => 'hour',
                                                                      :country => 'US',
                                                                      :region => 'TX',
                                                                      :city => 'Austin',
                                                                      :limit => 100,
                                                                      :page => 1,
                                                                      :count => true}

*Get a Single Campaign’s Click Opens: *

result = mg_client.get "#{domain}/campaigns/#{campaign_id}/opens", {:groupby => 'hour',
                                                                     :country => 'US',
                                                                     :region => 'TX',
                                                                     :city => 'Austin',
                                                                     :limit => 100,
                                                                     :page => 1,
                                                                     :count => true}

*Get a Single Campaign’s Click Unsubscribes: *

result = mg_client.get "#{domain}/campaigns/#{campaign_id}/unsubscribes", {:groupby => 'hour',
                                                                            :country => 'US',
                                                                            :region => 'TX',
                                                                            :city => 'Austin',
                                                                            :limit => 100,
                                                                            :page => 1,
                                                                            :count => true}

*Get a Single Campaign’s Click Complaints: *

result = mg_client.get "#{domain}/campaigns/#{campaign_id}/complaints", {:groupby => 'hour',
                                                                          :limit => 100,
                                                                          :page => 1,
                                                                          :count => true}

Webhooks:

---

*Get List of Webhooks: *

result = mg_client.get "domains/#{domain}/webhooks"

*Get a Webhook Properties: *

result = mg_client.get "domains/#{domain}/webhooks/#{webhook_id}"

*Create a Webhook: *

result = mg_client.post "domains/#{domain}/webhooks", {:id => 'bounce',
                                                        :url => 'http://example.com/mailgun/events/bounce'}

*Update a Webhook: *

result = mg_client.put "domains/#{domain}/webhooks/#{webhook_id}", {:id => 'bounce',
                                                                     :url => 'http://example.com/mailgun/events/bounce'}

*Remove a Webhook: *

result = mg_client.delete "domains/#{domain}/webhooks/#{webhook_id}"

Mailing Lists:

---

*Get list of Lists: *

result = mg_client.get "lists"

*Get List Properties: *

result = mg_client.get "lists/#{list_address}"

*Create a List: *

result = mg_client.post "lists", {:address => 'dev.group@samples.mailgun.org',
                                   :name => 'Development Group List',
                                   :description => 'List of all developers.',
                                   :access_level => 'members'}

*Update a List: *

result = mg_client.put "lists/#{list_address}", {:address => 'dev.group@samples.mailgun.org',
                                                  :name => 'Development Group List',
                                                  :description => 'List of all developers.',
                                                  :access_level => 'members'}

*Remove a List: *

result = mg_client.delete "lists/#{list_address}"

*Get List Members: *

result = mg_client.get "lists/#{list_address}/members"

*Get List Member Properties: *

result = mg_client.get "lists/#{list_address}/members/#{member_address}"

*Add Member to List: *

result = mg_client.post "lists/#{list_address}/members/#{member_address}", {:address => 'jane@samples.mailgun.org',
                                                                             :name => 'Jane Doe',
                                                                             :vars => '{"first": "Jane", "last": "Doe"}',
                                                                             :subscribed => true,
                                                                             :upsert => 'no'}

*Update Member on List: *

result = mg_client.put "lists/#{list_address}/members/#{member_address}", {:address => 'jane@samples.mailgun.org',
                                                                             :name => 'Jane Doe',
                                                                             :vars => '{"first": "Jane", "last": "Doe"}',
                                                                             :subscribed => true}

*Delete a Member from List: *

result = mg_client.delete "lists/#{list_address}/members/#{member_address}"

*Get Stats for List: *

result = mg_client.get "lists/#{list_address}/stats"

Email Validation:

---

*Validate Single Address: *

result = mg_client.get "address/validate", {:address => 'test@example.com'}

Support and Feedback

Be sure to visit the Mailgun official
documentation website for additional
information about our API.

If you find a bug, please submit the issue in Github directly.
Mailgun-Ruby Issues

As always, if you need additional assistance, drop us a note at
support@mailgun.com.