Mailgun Authentication: API Key & Basic Auth Guide (2026)

Authentication overview

Mailgun's API is designed to facilitate programmatic interaction with its email services, including sending emails, managing domains, and retrieving analytics. To ensure secure communication and prevent unauthorized access, all API requests must be authenticated. Mailgun primarily utilizes API keys for authentication, which are transmitted over HTTPS to protect credentials in transit. This approach aligns with common REST API security practices, where a unique, secret key identifies and authorizes the calling application or user.

The authentication process involves including your API key in the request header. Mailgun supports two primary methods for this: HTTP Basic Authentication and a custom Authorization header for specific scenarios. Adhering to these methods ensures that your API calls are processed securely and that your account resources remain protected from misuse. Understanding the specific implementation details for each method is crucial for successful integration and maintaining a robust security posture for your email operations.

Supported authentication methods

Mailgun primarily supports API key-based authentication for its RESTful API. This method ensures that requests originate from legitimate sources and have the necessary permissions to perform the requested operations. The API key acts as a secret token that must be presented with each API call.

1. HTTP Basic Authentication

The most common and recommended method for authenticating with Mailgun's API is through HTTP Basic Authentication as defined by RFC 7617. In this scheme, your API key is used as the password, and the username is typically api. The client encodes the username and password (api:YOUR_API_KEY) into a Base64 string and includes it in the Authorization header of the HTTP request, prefixed with Basic.

This method is widely supported across various programming languages and HTTP client libraries, making it straightforward to implement. When using Basic Authentication, ensure that all API communications occur over HTTPS to encrypt the credentials during transmission, preventing eavesdropping and man-in-the-middle attacks.

2. Custom Authorization Header (for specific SDKs/libraries)

While Basic Authentication is the standard, some Mailgun SDKs or specific use cases might handle the API key slightly differently, often by abstracting the Basic Auth mechanism or by placing the API key directly into a custom Authorization header with a Bearer prefix or similar. However, the underlying credential remains the same: your private API key. Always refer to the specific SDK documentation for the exact implementation if you are not using raw HTTP requests.

Table of Authentication Methods

Getting your credentials

Accessing your Mailgun API key is a straightforward process performed within the Mailgun Control Panel. Your API key is a critical credential that grants access to your account's email sending and management capabilities, so it must be treated with the same care as a password.

1. Log in to the Mailgun Control Panel: Navigate to the Mailgun documentation and sign in to your account.
2. Access API Keys Section: Once logged in, go to the 'API Keys' section, typically found under your profile or account settings. The exact path may vary slightly with UI updates, but it's generally labeled clearly.
3. Identify Your Private API Key: Mailgun provides different types of API keys, including a public validation key and a private API key. For sending emails and performing most API operations, you will need your private API key, which starts with key-.
4. Copy the Key: Copy the private API key to your clipboard. Be cautious not to expose this key publicly or embed it directly into client-side code where it could be extracted.

Mailgun also offers the ability to create and manage multiple API keys for different applications or team members. This allows for better access control and easier key rotation, enhancing your overall security posture. You can also revoke specific keys if they are compromised, without affecting other integrations.

Authenticated request example

This example demonstrates how to send an email using the Mailgun API with HTTP Basic Authentication via cURL. This method is widely used for testing and in scripting environments. Replace YOUR_API_KEY, YOUR_DOMAIN_NAME, and email addresses with your actual credentials and details.

curl -s --user 'api:YOUR_API_KEY' \
    https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages \
    -F from='Excited User <mailgun@YOUR_DOMAIN_NAME>' \
    -F to='Recipient <[email protected]>' \
    -F subject='Hello' \
    -F text='Testing some Mailgun awesomeness!'

In this example:

• --user 'api:YOUR_API_KEY': This flag instructs cURL to use HTTP Basic Authentication. api is the username, and YOUR_API_KEY is the password. cURL automatically Base64-encodes this and adds the Authorization: Basic ... header.
• https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages: This is the Mailgun API endpoint for sending messages. The v3 indicates the API version, and YOUR_DOMAIN_NAME should be replaced with a domain you have configured in your Mailgun account.
• -F from='...', -F to='...', -F subject='...', -F text='...': These flags are used to send form data (multipart/form-data) to the API, specifying the sender, recipient, subject, and body of the email.

For programmatic examples in various languages, refer to the Mailgun API Reference documentation, which provides code snippets tailored for Python, Ruby, PHP, Java, C#, Go, and Node.js.

Security best practices

Securing your Mailgun API keys and ensuring the integrity of your email communications is paramount. Adhering to these best practices will help protect your account from unauthorized access and potential abuse:

1. Keep API Keys Confidential

• Never hardcode keys in client-side code: API keys embedded in JavaScript or mobile applications can be easily extracted. Always use server-side components to make API calls to Mailgun.
• Use environment variables or secure configuration management: Store API keys as environment variables on your server or in a secure configuration management system (e.g., AWS Secrets Manager, Azure Key Vault, HashiCorp Vault). Avoid committing them directly into your codebase.
• Restrict access to keys: Limit who has access to your Mailgun API keys within your organization. Implement role-based access control (RBAC) to ensure only authorized personnel can view or modify them.

2. Use HTTPS Exclusively

• All communication with the Mailgun API should occur over HTTPS. This encrypts the data in transit, protecting your API key and email content from interception. Mailgun's API endpoints are designed to enforce HTTPS, but always ensure your client-side implementation specifies https://.

3. Implement IP Whitelisting

• Mailgun allows you to restrict API key usage to a specific set of IP addresses. Configure IP whitelisting in your Mailgun Control Panel to ensure that API calls using your key can only originate from trusted servers. This adds a crucial layer of defense against unauthorized access, even if a key is compromised.

4. Rotate API Keys Regularly

• Periodically rotate your API keys. This practice minimizes the window of exposure if a key is inadvertently compromised. Mailgun allows you to generate new keys and revoke old ones without service interruption.

5. Monitor API Usage

• Regularly review your Mailgun API logs and usage statistics for any unusual activity. Spikes in email sending, failures, or unexpected API calls could indicate a compromised key or malicious activity. Set up alerts for anomalous behavior.

6. Principle of Least Privilege

• While Mailgun's current API key model provides full access, if future features allow for scoped API keys, always generate keys with the minimum necessary permissions required for a specific application or service. This limits the potential damage if a key is compromised.

7. Secure Your Development Environment

• Ensure that your development machines and staging environments are secure. Avoid storing sensitive credentials directly on local machines or in insecure version control systems.

8. Error Handling and Logging

• Implement robust error handling in your application to gracefully manage authentication failures. Log these failures securely for auditing and to detect potential attack attempts, but avoid logging the API key itself.

By consistently applying these security measures, developers can significantly reduce the risk associated with using Mailgun's API and maintain the confidentiality and integrity of their email operations. For further security guidance, consult the Cloudflare API security considerations, which offer general principles applicable to many API integrations, including Mailgun.