Getting Started

Welcome to Mailgun!

APIs are at the heart of Mailgun. While most of the Mailgun service can be accessed through our RESTful HTTP API without the need to install any libraries, we have written libraries for a lot of the popular languages.

Mailgun features can be accessed through the Mailgun Control Panel using your browser and logging in at https://app.mailgun.com/app/dashboard.

If you have questions or need help, please feel free to contact our Support Team at https://app.mailgun.com/support

Let's get started!

Verifying Your Domain

Managing Role-Based Access Control (RBAC) API Keys

Domain Verification

verifydomain

Five reasons why you need to verify your domain:

  • To prove you are an authorized sender for the domain
  • Verified domains are not subject to a sending limit of 300 emails per day
  • No more "sent via Mailgun.org" message in your emails
  • Establishes a positive email reputation for your own domain
  • Mailgun is less suspicious of traffic that is being sent on verified domains and that reduces the likelihood of being disabled
Note:

For more information and help related to verifying domains, visit How Do I Verify My Domain? and Other DNS Questions.

Types of Domains

There are two types of Domains:

Sandbox Domain

Each new Mailgun account is automatically provisioned with a sandbox domain, sandbox <uniq-alpha-numeric-string\>@mailgun.org. This is for testing purposes only. Sandbox domains can only send to authorized recipients.

Your Sandbox Domain allows:

Note:

Sending limitations are also in effect for routes that are triggered by message addresses to the sandbox domain and mailing lists created under that domain.

To use your Sandbox Domain:

  1. Log in to your Mailgun account
  2. Go to the Mailgun Control Panel
  3. On the left side control panel, click Sending to expand the sidebar, then click Domains
  4. Click on your Sandbox Domain link to go to the Overview page
  5. On the Overview page, select API or SMTP to see quick instructions on how to send.

Custom Domains

To be able to use Mailgun in production, your custom domain(s) must be created and verified with Mailgun.

Add your domain:

  1. Go to the Mailgun Control Panel
  2. Select Domains from the left panel
  3. Click the Add New Domains button from the upper right corner
  4. Enter your domain name in the Domain name field
  5. Select Domain region
  6. Choose your IP assignment option
  7. Click the Add Domain button

Once a domain has been added, you will receive an email that you will need to respond to so that it can be verified.

Verifying your domain:

Go to Domain Verification Walkthrough for a step-by-step guide on how to verify your domain with Mailgun.

Note:

It can take 24-48 hours for DNS changes to propagate

  1. Add your domain or subdomain
  2. Open your DNS provider and add the two TXT DNS records provide
    • SPF (Sender Policy Framework): Sending server IP validation. This is used by most email providers.
    • DKIM (DomainKeys Identified Email): Like SPF, however cryptographic methods are used for validation.
  3. If you would like Mailgun to track clicks and opens, add the CNAME record
  4. MX records should also be added, unless you already have MX records for your domain pointed at another email service provider (e.g., Gmail)

Once you've added the records and they've been propagated, your domain will be verified.

Once you've added the two TXT records and they've been propagated, your domain will be verified. Verified domains will show up on the Mailgun Control Panel with a green Verified badge next to it.

For more on how to verify your domain, see this article on Domain Verification Walkthough.

Other DNS Records

  • CNAME (Canonical Name) DNS record with value mailgun.org should be added if you want Mailgun to track clicks, opens, and unsubscribes.
  • MX (Mail Exchange) records are required if you would like Mailgun to receive route/store messages addressed to the domain recipients. You will need to configure two (2) MX records with values 10 mxa.mailgun.org and 10 mxb.mailgun.org

DNS Records Summary

Type Required Purpose Value
TXT Domain Verification (SPF) v=spf1 include:mailgun.org ~all
TXT Domain Verification (DKIM) Find this record in "Domain Verification & DNS" section of the settings page for a particular domain in the Mailgun control panel.
CNAME Enables tracking mailgun.org
MX Enables receiving 10 mxa.mailgun.org
MX Enables receiving 10 mxb.mailgun.org

Common DNS Providers Documentation

Provider Link to Documentation
Go Daddy MX

CNAME

TXT

NameCheap All Records
Network Solutions MX

CNAME

TXT

Rackspace Email & Apps All Records
Rackspace Cloud DNS Developers Guide
Amazon Route 53 Developer Guide

Managing Role-Based Access Control (RBAC) API Keys

Roles Based Access Control (RBAC) API Keys empower admin users to generate API keys utilizing predefined roles that dictate the access level of each key.

Note:
  • Assigned roles cannot be updated. You will need to create a new key. Be sure to save the key in a safe place, as you will only be able to see it once when you create it.
  • Role-Based Access Control is only available on specific plans. See our Pricing page for more details https://www.mailgun.com/pricing/

Custom Message Limit

The Custom Message Limit imposes a hard limit on how many messages your account can send during a calendar month. The primary account holder will receive an e-mail notification when 50% and 75% of the limit has been crossed. After the limit has been reached, the account will be disabled until the beginning of the following month, or until it has been re-enabled in the dashboard or by modifying the message limit via API.

Note:

Only Admins have read/write access. All other roles will have read access.

API Permissions

During the API key creation process, you will be able to select a predefined role. This role assigns certain access levels to various public API endpoints. Read and write privileges are based on the role assigned to the API key.

Permission Type Description
No Access Will have no access to certain public API endpoints.
Read: Allows the API key to access GET endpoints within the selected permission.
Read/Write: Allows the API Key to access GET,PATCH,PUT,DELETE, and POST endpoints within the selected permission.

RBAC API Key Permissions Based on Role

The assigned roles below determines the API key’s permissions (or access and rights) per public API endpoint.

Endpoints Admin Analyst Developer Support
Domains Read/Write Read Read/Write Read
Messages Read/Write Read Read/Write Read
Webhooks Read/Write Read Read/Write Read
Events Read/Write Read Read/Write Read
Tags Read/Write Read Read/Write Read
Stats Read/Write Read Read/Write Read
Unsubscribes(suppressions) Read/Write No Access Read/Write Read/Write
Complaints (suppressions) Read/Write No Access Read/Write Read/Write
Bounces (suppressions) Read/Write No Access Read/Write Read/Write
Whitelist Read/Write Read Read/Write Read/Write
Routes Read/Write Read Read/Write Read
Mailing Lists Read/Write Read Read/Write Read/Write
Templates Read/Write Read Read/Write Read
IPs Read/Write Read Read/Write Read
IP Pools Read/Write Read Read/Write Read
Sub-Accounts Read/Write Read Read/Write Read
Validations Read/Write Read Read/Write Read
Secure Tracking Read/Write Read Read/Write Read
Custom Message Limits Read/Write Read Read Read