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"**Send a basic message: **
data = {:from => 'bob@sending_domain.com',
:to => '[email protected]',
:subject => 'The Ruby SDK is awesome!',
:text => 'It is really easy to send a message!'}
mg_client.send_message "sending_domain.com", dataSend a multipart text/html message:
data = {:from => 'bob@sending_domain.com',
:to => '[email protected]',
:subject => 'The Ruby SDK is awesome!',
:text => 'This is the text part.',
:html => '<html><body><p>This is the HTML part.</p></body></html>'}
mg_client.send_message "sending_domain.com", dataSend a custom MIME message:
# Don't include a file, pull the file to a string
mime_string = 'From: Bob Sample <[email protected]>
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 => '[email protected]', :message => mime_string}
mg_client.send_message "sending_domain.com", dataBuild a message, part by part, with Message Builder:
mb_obj = Mailgun::MessageBuilder.new
mb_obj.set_from_address "[email protected]", {'first' => 'Sending', 'last' => 'User'}
mb_obj.add_recipient :to, "[email protected]", {'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_objBuild a message with attachments, part by part, with Message Builder:
mb_obj = Mailgun::MessageBuilder.new
mb_obj.set_from_address "[email protected]", {'first' => 'Sending', 'last' => 'User'}
mb_obj.add_recipient :to, "[email protected]", {'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_objSend batches of 1000 messages per post:
bm_obj = Mailgun::BatchMessage.new
# Build message using Message Builder
bm_obj.set_from_address "[email protected]", {'first' => 'Sending', 'last' => 'User'}
bm_obj.set_message_id("<[email protected]>") # 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, "[email protected]"
# All message IDs returned in finalize method return
message_ids = @bm_obj.finalizeGet 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}"**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 => '[email protected]', :tag => 'mypromotion'}**Unsubscribe from all messages for a domain: **
result = @mg_client.post "#{domain}/unsubscribes", {:address => '[email protected]', :tag => '*'}**Remove an unsubscribe: **
result = @mg_client.delete "#{domain}/unsubscribes/#{email_address}"**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 => '[email protected]'}**Remove a complaint: **
result = @mg_client.delete "#{domain}/complaint/#{email_address}"**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 => '[email protected]',
:code => 550,
:error => 'Mailbox does not exist.'}**Remove a Bounced Address: **
result = @mg_client.delete "#{domain}/bounces/#{email_address}"**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}"**Get Event: **
result = @mg_client.get "#{domain}/events", {:event => 'rejected'}**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("[email protected]")'}**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("[email protected]")'}**Remove a Route: **
result = @mg_client.delete "routes/#{route_id}"**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 => '[email protected]',
: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}**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}"**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 => '[email protected]',
:name => 'Development Group List',
:description => 'List of all developers.',
:access_level => 'members'}**Update a List: **
result = @mg_client.put "lists/#{list_address}", {:address => '[email protected]',
: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 => '[email protected]',
: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 => '[email protected]',
: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"**Validate Single Address: **
result = @mg_client.get "address/validate", {:address => '[email protected]'}**Parse Addresses: **
result = @mg_client.get "address/parse", {:addresses => '[email protected], "First Last <[email protected]>',
:syntax_only => true}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 [email protected].