Mailgun Getting Started: Setup, API Keys, and First Send (2026)

Getting started overview

Integrating mail.gw, commonly known as Mailgun, into an application involves a series of steps designed to enable programmatic email sending and management. This guide focuses on the initial setup, credential acquisition, and executing a foundational API request. The typical workflow includes account registration, domain verification to establish sending authorization, and obtaining the necessary API keys for authentication. Once these prerequisites are met, developers can use Mailgun's RESTful API or one of its official SDKs to send emails, manage mailing lists, and track email eventsprogrammatically.

Mailgun offers a free tier that includes 5,000 emails per month for the first three months, providing an opportunity for developers to test and integrate the service without immediate cost. This free tier is followed by paid plans, such as the Foundation plan, which starts at $35 per month for 50,000 emails and scales with volume requirements. Mailgun supports various compliance standards, including GDPR and SOC 2 Type II, with HIPAA compliance available as an add-on, addressing diverse regulatory needs.

Create an account and get keys

To begin using Mailgun, the first step is to create an account. This process typically involves providing basic contact information and agreeing to the terms of service. Upon successful registration, you will gain access to the Mailgun Control Panel, which serves as the central hub for managing domains, viewing logs, and accessing API credentials.

Domain Verification: Before sending emails, it is crucial to verify your sending domain. This step confirms to Mailgun that you own or have permission to send emails from the specified domain. Verification usually involves adding specific DNS records (TXT, MX, CNAME) to your domain's DNS settings. Mailgun provides the exact records you need to add within the Control Panel under the 'Domains' section. Proper domain verification is essential for email deliverability and to prevent your emails from being flagged as spam.

API Keys: Mailgun uses API keys for authenticating requests. There are generally two types of API keys:

• Private API Key: Used for most API interactions, including sending emails, managing domains, and accessing logs. This key should be kept confidential and never exposed in client-side code.
• Public Validation Key: Used for client-side validation of email addresses. This key can be exposed publicly as it only allows validation and does not grant access to sensitive account information.

You can find your API keys in the Mailgun Control Panel by navigating to Settings > API Keys. The private API key will typically start with key-. Copy this key, as it will be required for all authenticated API requests.

Your first request

Once your domain is verified and you have your API key, you can send your first email. This example uses cURL, a common command-line tool for making HTTP requests, as it directly demonstrates the API interaction without requiring an SDK setup. Mailgun's email sending API endpoint typically uses HTTP POST requests.

API Endpoint Structure:

The base URL for sending emails is api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages.

Replace YOUR_DOMAIN_NAME with the domain you have verified in your Mailgun account.

Authentication:

Mailgun uses HTTP Basic Authentication. The username is always api, and the password is your Private API Key (e.g., key-YOUR_API_KEY).

Example cURL Request:

curl -s --user 'api:YOUR_PRIVATE_API_KEY' \
    https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages \
    -F from='Excited User <mailgun@YOUR_DOMAIN_NAME>' \
    -F to='[email protected]' \
    -F subject='Hello from Mailgun!' \
    -F text='Congratulations, you just sent an email with Mailgun!'

Replace the placeholders:

• YOUR_PRIVATE_API_KEY: Your actual Mailgun Private API Key.
• YOUR_DOMAIN_NAME: The domain you added and verified in Mailgun.
• [email protected]: The email address where you want to send the test email.

Upon successful execution, the API will return a JSON response indicating the message ID and a confirmation:

{
  "id": "<20260529123456.12345.example@YOUR_DOMAIN_NAME>",
  "message": "Queued. Thank you."
}

This response confirms that Mailgun has accepted your email for delivery. You should then check the recipient's inbox for the email. If you encounter issues, refer to the Mailgun logs in the Control Panel for detailed delivery status and error messages.

For developers preferring a specific programming language, Mailgun provides SDKs for Python, Ruby, Java, PHP, Go, and Node.js. These SDKs abstract the HTTP request details and provide a more idiomatic way to interact with the API. For instance, in Python, you might use the requests library or the official Mailgun Python SDK to achieve the same result with fewer lines of code.

Common next steps

After successfully sending your first email, several common next steps can enhance your Mailgun integration:

1. Implement Webhooks: Mailgun offers webhooks to notify your application of email events such as delivered, failed, opened, and clicked. Configuring webhooks allows for real-time tracking and automation based on email engagement. You can set up webhooks in the Mailgun Control Panel under Webhooks for your domain. Implementing webhook security, such as signature verification, is recommended to ensure the authenticity of incoming requests.
2. Manage Mailing Lists: For sending to multiple recipients or managing subscriptions, Mailgun's mailing list API is useful. This allows you to programmatically add, remove, and update members in various lists, which is common for newsletters or marketing campaigns.
3. Email Validation: Integrate Mailgun's email validation service to reduce bounce rates and improve deliverability. This API can check if an email address is valid, disposable, or likely to bounce before you send to it. The Email Validation API documentation provides details on its usage.
4. Inbound Routing: Configure inbound routes to process incoming emails. This feature allows you to forward incoming emails to another email address, post them to a URL, or store them for later retrieval. This is particularly useful for handling replies or processing user-generated content sent via email.
5. Explore Advanced Sending Options: Mailgun supports various advanced sending options, including scheduled sending, custom headers, and template engines. These features provide greater control and flexibility over your email campaigns.
6. Review Analytics and Logs: Regularly check the Mailgun Control Panel for analytics and logs. The logs provide detailed information about each email sent, including delivery status, errors, and recipient interactions, which are invaluable for troubleshooting and optimizing email performance.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

• Check API Key: Ensure you are using the correct Private API Key and that it is correctly formatted in your request (e.g., api:key-YOUR_API_KEY for basic authentication). A common mistake is using the public validation key instead of the private API key.
• Verify Domain Name: Double-check that the domain name in your API request matches exactly the domain you verified in your Mailgun Control Panel. Mismatches will result in authentication or domain-related errors.
• DNS Records: Confirm that your domain's DNS records (TXT, MX, CNAME) are correctly set up and have propagated. DNS changes can take some time to propagate globally (up to 48 hours, though often faster). You can use online DNS lookup tools to verify propagation.
• Endpoint URL: Ensure the API endpoint URL is correct and includes your verified domain name (https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages).
• Firewall/Network Issues: If you are making requests from a restricted network, ensure that outbound connections to api.mailgun.net on port 443 (HTTPS) are not blocked by a firewall.
• Mailgun Logs: The most valuable resource for troubleshooting is the Mailgun Control Panel's logs. Navigate to Logs under your domain to see detailed error messages and delivery statuses for each email attempt. These logs often provide specific reasons for failures, such as invalid recipients or authentication errors.
• Recipient Email Address: Verify that the to email address in your request is valid and able to receive emails. Test with a known working email address first.
• Request Body/Parameters: Ensure all required parameters (from, to, subject, text) are present and correctly formatted in your request.
• Mailgun Status Page: Check the Mailgun Status Page to see if there are any ongoing service disruptions or outages that might be affecting email delivery.