Need help with mailgun?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

123 Stars 57 Forks MIT License 170 Commits 17 Opened issues


mailgun library for ruby

Services available


Need anything else?

Contributors list

Mailgun rubygem

This gem allows for idiomatic Mailgun usage from within ruby. Mailgun is a kickass email-as-a-service that lets you use email as if it made sense. Check it out at

Mailgun exposes the following resources:

  • Sending email
  • Mailing Lists
  • Mailing List Members
  • Mailboxes
  • Routes
  • Log
  • Stats
  • Messages
  • Bounces
  • Unsubscribes
  • Complaints
  • Domain management
  • Webhook management
  • Address Validation

Patches are welcome (and easy!).

Sending mail using ActionMailer

If you simply want to send mail using Mailgun, just set the smtp settings in the Rails application like the following. Replace wherever necessary in the following snippet :)

ActionMailer::Base.smtp_settings = {
  :port           => 587,
  :address        => '',
  :user_name      => '[email protected]',
  :password       => 'mailgun-smtp-password',
  :domain         => 'your.mailgun.domain',
  :authentication => :plain,
ActionMailer::Base.delivery_method = :smtp


We mimic the ActiveRecord-style interface.


# Initialize your Mailgun object:
Mailgun.configure do |config|
  config.api_key = 'your-api-key'
  config.domain  = 'your-mailgun-domain'

@mailgun = Mailgun()

or alternatively:

@mailgun = Mailgun(:api_key => 'your-api-key')

Sending Email

parameters = {
  :to => "[email protected]",
  :subject => "missing tps reports",
  :text => "yeah, we're gonna need you to come in on friday...yeah.",
  :from => "[email protected]"

Mailing Lists

# Create a mailing list
@mailgun.lists.create "[email protected]"

List all Mailing lists


Find a mailing list

@mailgun.lists.find "[email protected]"

Update a mailing list

@mailgun.lists.update("[email protected]", "[email protected]", "Developers", "Develepor Mailing List")

Delete a mailing list

@mailgun.lists.delete("[email protected]")

Mailing List Members

# List all members within a mailing list
@mailgun.list_members.list "[email protected]"

Find a particular member in a list

@mailgun.list_members.find "[email protected]", "[email protected]"

Add a member to a list

@mailgun.list_members.add "[email protected]", "[email protected]"

Add multiple mailing list members to a list (limit 1,000 per call)

@mailgun.list_members.add_multi "[email protected]", [{"address": "Alice ", "vars": {"age": 26}}, {"name": "Bob", "address": "[email protected]", "vars": {"age": 34}}].to_json, {:upsert => true}

Update a member on a list

@mailgun.list_members.update "[email protected]", "[email protected]", "Q", {:gender => 'male'}.to_json, :subscribed => 'no')

Remove a member from a list

@mailgun.list_members.remove "[email protected]", "[email protected]"


# Create a mailbox
@mailgun.mailboxes.create "[email protected]", "password"

List all mailboxes that belong to a domain

@mailgun.mailboxes.list ""

Destroy a mailbox (queue bond-villian laughter)

"I'm sorry Bond, it seems your mailbox will be... destroyed!"

@mailbox.mailboxes.destroy "[email protected]"


# List last bounces (100 limit)

Find bounces

@mailgun.bounces.find "[email protected]"

Add bounce

@maligun.bounces.add "[email protected]"

Clean user bounces

@mailbox.bounces.destroy "[email protected]"


# Initialize your Mailgun object:
@mailgun = Mailgun(:api_key => 'your-api-key')

Create a route

Give it a human-readable description for later, a priority

filters, and actions

@mailgun.routes.create "Description for the new route", 1, [:match_recipient, "[email protected]"], [[:forward, ""], [:stop]]

List all routes that belong to a domain

limit the query to 100 routes starting from 0

@mailgun.routes.list 100, 0

Get the details of a route via its id

@mailgun.routes.find "4e97c1b2ba8a48567f007fb6"

Update a route via its id

(all keys are optional)

@mailgun.routes.update "4e97c1b2ba8a48567f007fb6", { :priority => 2, :expression => [:match_header, :subject, "*.support"], :actions => [[:forward, ""]] }

Destroy a route via its id

@mailbox.routes.destroy "4e97c1b2ba8a48567f007fb6"

Supported route filters are:

, and

Supported route actions are:

, and


# Add a domain ""

List all domains that belong to the account

Get info for a domain ""

Remove a domain ""


# List of currently available webhooks

Returns a list of webhooks set for the specified domain


Returns details about the webhook specified


Creates a new webhook

Note: Creating an Open or Click webhook will enable Open or Click tracking

@mailgun.webhooks.create(:open, "")

Updates an existing webhook

@mailgun.webhooks.update(:open, "")

Deletes an existing webhook

Note: Deleting an Open or Click webhook will disable Open or Click tracking


Address Validation

Requires the

to be set. The Mailgun public key is available in the My Account tab of the Control Panel. ```ruby

Given an arbitrary address, validates address based off defined checks

@mailgun.addresses.validate('[email protected]') ```

Making Your Changes

  • Fork the project (Github has really good step-by-step directions)

  • Start a feature/bugfix branch

  • Commit and push until you are happy with your contribution

  • Make sure to add tests for it. This is important so we don't break it in a future version unintentionally.

  • After making your changes, be sure to run the Mailgun tests using the

    rspec spec
    to make sure everything works.
  • Submit your change as a Pull Request and update the GitHub issue to let us know it is ready for review.


  • Add skip and limit functionality
  • Distinguish failed in logs
  • Distinguish delivered in logs
  • Tracking?
  • Stats?
  • Campaign?



See file for contributor credits.


Released under the MIT license. See LICENSE for more details.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.