Mailgun Authentication: Methods, Credentials, & Security (2026)

Authentication overview

Mailgun employs a credential-based authentication model to secure access to its API and SMTP services. This model ensures that only authorized applications and users can send emails, manage domains, and interact with Mailgun's features programmatically. The core principle involves verifying the identity of the client (your application or email client) against credentials issued by Mailgun before processing any requests or sending any messages. This mechanism is critical for maintaining the integrity and security of email transmission processes and preventing unauthorized usage of sending infrastructure.

Authentication is required for all interactions with the Mailgun API, which includes sending emails, managing domains, retrieving logs, and manipulating routes. Similarly, when configuring an email client or server to send messages through Mailgun's SMTP servers, specific SMTP credentials are required. The choice of authentication method typically depends on the client's architecture and the specific Mailgun service being accessed. For instance, web applications commonly use API keys for direct HTTP requests, while legacy systems or email clients might opt for SMTP authentication.

Understanding and correctly implementing Mailgun's authentication protocols is fundamental for successful integration and secure operation. Improper handling of credentials can lead to unauthorized access, potential service disruption, and compromise of email sending capabilities. Mailgun provides various tools and documentation to facilitate secure credential management and integration, aligning with general API security best practices for developers.

Supported authentication methods

Mailgun primarily supports two distinct authentication methods, each tailored for specific use cases:

• API Keys (HTTP Basic Authentication): This is the recommended method for programmatic access to the Mailgun API for tasks such as sending emails, managing domains, or retrieving analytics. API keys are long, randomly generated strings that act as a secret token. When making HTTP requests to the Mailgun API, these keys are typically passed in the Authorization header using HTTP Basic Authentication, where the username is api and the password is your API key. This method is suitable for server-to-server communication where the key can be securely stored and managed.
• SMTP Credentials: For sending emails through an email client, an application that connects via SMTP, or a library that uses SMTP, Mailgun requires SMTP specific credentials. These consist of a username (which is often a full email address associated with your Mailgun domain) and a password. SMTP authentication typically occurs during the initial connection handshake with Mailgun's SMTP servers, ensuring only authenticated clients can relay messages. This method is fundamental for traditional email sending architectures.

The following table summarizes Mailgun's supported authentication methods:

Both methods rely on TLS/SSL encryption for all communications to protect credentials and data in transit. For detailed information on API key usage, refer to the Mailgun API Reference documentation.

Getting your credentials

Accessing your Mailgun credentials typically involves navigating through the Mailgun Control Panel. Here's a general guide:

1. Log In to Your Mailgun Account: Begin by logging into your Mailgun account via their official website. If you don't have an account, you'll need to sign up first.
2. Navigate to the API Keys Section: Once logged in, look for a section related to 'API Keys' or 'Security' in the left-hand navigation menu or your user settings. The exact path may vary slightly but typically involves navigating to 'Settings' and then 'API Keys'.
3. Retrieve Your API Key: Your primary API key will be displayed there. It's often labeled as 'Private API Key' or similar. It's crucial to treat this key as a sensitive secret. Mailgun may also provide a 'Public API Key' which has limited permissions and is suitable for client-side use for specific functions like email validation, though the private key is for sending.
4. Access SMTP Credentials: For SMTP access, you typically need to manage your sending domains. Navigate to 'Sending' > 'Domains'. Select the domain you wish to configure. Within the domain's settings, you will find 'SMTP Credentials'. Here you can view existing credentials or create new ones. Mailgun often provides a default SMTP login (username) for your domain and allows you to set or reset its password.
5. Store Credentials Securely: After retrieving your credentials, store them in a secure manner. Avoid hardcoding them directly into your application's source code. Instead, use environment variables, a secrets manager, or a configuration file that is not committed to version control.

For more specific instructions and visual guides on locating and managing your credentials, consult the official Mailgun documentation, which provides up-to-date details on their interface.

Authenticated request example

This section demonstrates how to make an authenticated request to the Mailgun API using cURL, which is a common command-line tool for making HTTP requests. The example shows sending an email, which is one of the most frequent uses of the Mailgun API.

Before executing this example, replace YOUR_API_KEY with your actual private API key, YOUR_DOMAIN_NAME with your verified sending domain, and update the recipient and sender email addresses.

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='[email protected]' \
    -F subject='Hello' \
    -F text='Testing some Mailgun awesomeness!'

In this cURL command:

• -s: Suppresses the progress meter.
• --user 'api:YOUR_API_KEY': This specifies the HTTP Basic Authentication credentials. The username is fixed as api, and the password is your Mailgun private API key. This is the mechanism by which Mailgun authenticates your API request.
• 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 specifies the domain from which the email will be sent.
• -F from='...', -F to='...', -F subject='...', -F text='...': These are form data parameters that define the email's sender, recipient, subject, and body content, respectively.

For programmatic implementations in various languages, Mailgun provides official SDKs (Python, Ruby, Java, PHP, Go, Node.js) that abstract away the raw HTTP request details, making authentication and API calls simpler. For example, in Python, you might use their library as shown in the Mailgun API documentation examples, where the API key is passed during the client initialization.

Security best practices

Securing your Mailgun credentials and API access is paramount to prevent unauthorized email sending and data breaches. Adhering to these best practices can significantly enhance the security posture of your integration:

• Never Hardcode API Keys: Avoid embedding API keys directly into your source code. Instead, use environment variables, configuration files that are excluded from version control (e.g., via .gitignore), or dedicated secret management services. This prevents accidental exposure of keys in public repositories or deployment artifacts.
• Use Dedicated API Keys: For different applications or environments (development, staging, production), consider generating separate API keys. This allows for more granular control and easier revocation if a key is compromised for a specific service without affecting others.
• Implement Key Rotation: Regularly rotate your API keys and SMTP passwords. This practice limits the window of exposure for any compromised credential. Mailgun's control panel allows you to generate new keys and revoke old ones. The frequency of rotation should align with your organization's security policies.
• Restrict IP Access (if available): If Mailgun offers IP whitelist functionality (check their latest documentation), configure it to allow API requests only from known, trusted IP addresses of your servers. This adds a layer of network-level security.
• Use TLS/SSL for All Communications: Ensure that all API requests and SMTP connections to Mailgun use Transport Layer Security (TLS) or Secure Sockets Layer (SSL). Mailgun's endpoints are designed to enforce TLS/SSL, meaning unencrypted connections will typically fail. This encrypts credentials and message content in transit, protecting against eavesdropping. This is a fundamental principle of HTTPS for secure web communication.
• Monitor API Usage: Regularly review your Mailgun logs and usage patterns for any unusual activity. Spikes in email sending, failures, or access from unexpected locations could indicate a compromised key. Set up alerts for suspicious events if possible.
• Principle of Least Privilege: If Mailgun supports roles or permissions for API keys (e.g., a key only for sending, another for managing domains), grant only the minimum necessary permissions to each key. A key used solely for sending emails should not have permissions to delete domains.
• Secure Your Development Environment: Ensure that your local development environment and CI/CD pipelines are secure. Credentials used during development or deployment should be handled with the same care as production credentials.
• Educate Your Team: Ensure that all developers and team members who interact with Mailgun credentials are aware of these security best practices and understand the implications of mishandling sensitive information.