Getting Started

Welcome to Mailgun!

APIs are at the heart of Mailgun. Our goal is to provide developers worldwide with an accessible and straightforward way to send, receive, and track emails effortlessly. To get you familiar with Mailgun's APIs, here are some things you should know:

APIs

• The Mailgun API is built on HTTP
• Our API is RESTful which:
  • Uses predictable, resource-oriented URLs.
  • Uses built-in HTTP capabilities for passing parameters and authentication.
  • Responds with standard HTTP response codes to indicate errors.
  • Returns JSON .

While most of the Mailgun service can be accessed through our RESTful HTTP APIs without the need to install any libraries, you have the option to choose from these languages:

• Node.js
• Go
• PHP
• Java
• Ruby

Base URL

All API calls referenced in our documentation start with a base URL. Mailgun allows the ability to send and receive email in both US and EU regions. Be sure to use the appropriate base URL based on which region you have created for your domain.

It is also important to note that Mailgun uses URI versioning for our API endpoints, and some endpoints may have different versions than others. Please reference the version stated in the URL for each endpoint.

For domains created in our US region the base URL is:

https://api.mailgun.net/

For domains created in our EU region the base URL is:

https://api.eu.mailgun.net/

Your Mailgun account may contain multiple sending domains. To avoid passing the domain name as a query parameter, most API URLs must include the name of the domain you are interested in:

https://api.mailgun.net/v3/mydomain.com

Authentication

Authentication to the Mailgun API is done by providing an Authorization header using HTTP Basic Auth:

• Username: api
• Password: Your API key

Mailgun provides two types of API keys for authenticating against the API:

Primary account API key

When you sign up for Mailgun, a primary account API key is generated. This key allows you to perform all CRUD operations via our various API endpoints and for any of your sending domains. To view your primary account API key:

1. Go to the Mailgun Dashboard
2. Click on Account** Settings** on the right-hand side.
3. Select API Keys and click on the eye icon next to Private API key.

Domain Sending Keys

Domain Sending Keys are API keys that only allow sending messages via a POST call on /messages and /messages.mime endpoints for the domain in which they are created for. To create a sending API key:

1. Go to the Mailgun Dashboard
2. Click the Sending tabon the left-hand side of the Mailgun dashboard
3. Click the Domains tab and select the domain in which you wish to add a sending key to
4. Click the Domain Settings and navigate to the Sending API keys tab
5. Click on Add Sending Key

Give your key a suitable description (such as the name of the application or client you are creating the key for) and click Create Sending Key

Copy your API key and keep it in a safe place. For security purposes, we will not be able to show you the key again. If you lose your key, you will need to create a new key.

Here is how you use basic HTTP auth with curl:

curl --user 'api:YOUR_API_KEY'

Date Format

Mailgun returns JSON for all API calls. JSON does not have a built-in date type; dates are passed as strings encoded according to RFC 2822#page-14. This format is native to JavaScript and is also supported by most programming languages out of the box:

'Thu, 13 Oct 2011 18:02:00 +0000'

Mailgun Regions

Using a single account and billing plan, you can choose to provision new sending domains in the EU environment. It is important to note that message data never leaves the region in which it is processed. Only a limited amount of account data is replicated globally, giving you a single account from which to manage domains in both the US and the EU.

Here are the specifics on the type of data that is replicated globally versus what is region-bound:

Below are the endpoints you will use for sending/receiving/tracking messages in the EU:

Mailgun Features

Mailgun features can be accessed through Mailgun's Control Panel by logging in at https://app.mailgun.com/app/dashboard.

Here’s a lightweight overview of what Mailgun can do:

Email Sending

• Transactional Emails: Send automated emails like order confirmations, password resets, and notifications.
• Bulk Emails: Efficiently send large volumes of emails with optimized delivery performance.
• SMTP Integration: Seamlessly integrate Mailgun with your application via SMTP.
• Support for custom templates, mailing lists, etc.

Email Receiving

• Inbound Parsing: Parse incoming emails to your domains and route them to your application with ease.
• Route Management: Define rules for handling incoming emails, such as forwarding to a specific address or storing the email.

Email Tracking

• Open and Click Tracking: Monitor who opens your emails and clicks on links, providing insights into recipient engagement.
• Bounce Tracking: Identify and manage bounced emails to maintain a clean email list.
• Webhooks: Set up webhooks to receive real-time notifications about email events.

Analytics and Reporting

• Detailed Reports: Access comprehensive reports on email delivery, open rates, click rates, and more.
• Event Tracking: Track specific email events like deliveries, opens, clicks, and bounces for granular insights.

Security and Compliance

• DKIM and SPF: Authenticate your emails to improve deliverability and protect against spoofing.
• DMARC: Implement DMARC policies to monitor and protect your domain from email phishing and spoofing.
• Our full list of compliance certificates are available via our trust portal

Domain and IP management tools

• IP Pooling: Manage IP pools to optimize email delivery and maintain sender reputation.
• Suppression Management: Automatically handle unsubscribes, complaints, and bounces to maintain a clean email list.
• Domain management: Add US or EU based domains, as well as manage their settings and sending.

User-Friendly Control Panel

• Web Interface: Manage your email campaigns, view analytics, and configure settings through an intuitive web interface.

Please continue to read through the user manual to see all supported functionality, and if at any point in your journey you have questions or need help, please feel free to contact our Support Team here

Let's get started!