mailgun

library1.9.0pypypi✓ verified 23d ago

The `mailgun` Python SDK provides a convenient interface for interacting with the Mailgun email API. It simplifies sending, receiving, and managing emails, domains, and webhooks programmatically. The library is actively maintained, with regular minor releases adding new API endpoint support and features like async client functionality. The current stable version is 1.6.0.

communication

pip install mailgun

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · MAILGUN

mailgun

communicationpythonv1.9.0

Install

2.8s avg

Import

571ms

Disk

24MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.8.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.596s · 25.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.8s · import 0.546s · 26MB

24MB installed

● package 24MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ from mailgun.client import Client

AsyncClient

✓ from mailgun.client import AsyncClient

Use for asynchronous applications with non-blocking I/O.

This quickstart demonstrates how to initialize the Mailgun client and send a basic text email using environment variables for API key and domain. Ensure `MAILGUN_API_KEY`, `MAILGUN_DOMAIN`, and optionally `MAILGUN_API_BASE_URL` are set. Remember to replace `test@example.com` with an authorized recipient.

import os from mailgun.client import Client def send_simple_message(): api_key = os.environ.get('MAILGUN_API_KEY', 'YOUR_MAILGUN_API_KEY') domain = os.environ.get('MAILGUN_DOMAIN', 'YOUR_MAILGUN_DOMAIN') # Use the appropriate API base URL for your region (US or EU) # For US: api_base_url = "https://api.mailgun.net/v3" # For EU: api_base_url = "https://api.eu.mailgun.net/v3" api_base_url = os.environ.get('MAILGUN_API_BASE_URL', "https://api.mailgun.net/v3") if not api_key or not domain: print("Please set MAILGUN_API_KEY and MAILGUN_DOMAIN environment variables.") return client = Client(auth=("api", api_key), api_url=f"{api_base_url}/{domain}") try: response = client.send_message( from_email="Excited User <mailgun@{}>.format(domain)", to_emails=["test@example.com"], # Replace with a verified recipient subject="Hello from Mailgun Python SDK", text="Congratulations, you just sent an email with Mailgun Python SDK!" ) print(f"Mailgun API response: {response.status_code} - {response.json()}") except Exception as e: print(f"An error occurred: {e}") if __name__ == "__main__": send_simple_message()

Debug

Known issues

gotchaMailgun operates in different regions (US and EU). Using the incorrect API base URL (`api_url` in the client constructor) for your domain's region will result in API errors.

fix

Set the `api_url` parameter in `mailgun.client.Client` or `mailgun.client.AsyncClient` to match your Mailgun domain's region (e.g., `https://api.eu.mailgun.net/v3` for EU).

affects: All versions

gotchaWhen using a Mailgun sandbox domain, all recipient email addresses must be manually added and verified within the Mailgun control panel before you can send emails to them. Attempts to send to unverified recipients will fail.

fix

Add and verify recipient email addresses in your Mailgun dashboard under the 'Sandbox Domains' section.

affects: All versions

gotchaThe 'from' email address used when sending messages must be associated with your verified Mailgun domain or sandbox domain. Sending from an unverified 'from' address will result in an API error.

fix

Ensure the `from_email` parameter in `send_message` uses an email address that belongs to a domain you have configured and verified in Mailgun.

affects: All versions

gotchaThe `AsyncClient` (introduced in v1.5.0) provides asynchronous functionality but requires `await` for all method calls, consistent with `asyncio` patterns. Mixing synchronous `Client` usage with `AsyncClient` methods or forgetting `await` will lead to runtime errors.

fix

When using `AsyncClient`, ensure your code is within an `async` function and all client method calls are `await`ed. For synchronous operations, use the `Client`.

affects: >=1.5.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'mailgun'

The `mailgun` Python package has not been installed in your current environment.

fix

Install the library using pip: `pip install mailgun`

401 Forbidden / 535 Authentication failed

Your Mailgun API key or domain is incorrect, or you are using the wrong API endpoint for your account's region (US vs. EU). This can also occur if the domain is not verified or the API key is of the wrong type (e.g., public key instead of private).

fix

Double-check your API key (ensure it's the private/sending key starting with 'key-'), your domain name, and the API endpoint URL (e.g., `https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages` for US or `https://api.eu.mailgun.net/v3/YOUR_DOMAIN_NAME/messages` for EU). Verify your domain in the Mailgun dashboard.

Emails not sending but code runs without error (HTTP 200 OK response)

Your API call was syntactically correct and accepted by Mailgun, but the emails were not delivered due to Mailgun-side restrictions. Common causes include using a sandbox domain to send to unverified recipients, an unverified sending domain, or incorrect 'from' email address not associated with your domain.

fix

Check your Mailgun 'Logs' or 'Events' dashboard for detailed delivery failures and error messages. If using a sandbox domain, ensure recipient emails are added as 'Authorized Recipients'. Verify your sending domain and ensure the 'from' address is valid and linked to your domain.

'from' parameter is not a valid address / Invalid recipient address

The email address provided in the 'from' or 'to' parameters is malformed, contains extra spaces, or does not adhere to standard email format requirements. It can also occur if the 'from' address is not associated with your sending domain.

fix

Ensure all email addresses are correctly formatted (e.g., `Sender Name <sender@example.com>` or `sender@example.com`) and do not contain typos or extra characters. Confirm the 'from' email address is allowed for your sending domain in Mailgun.

AttributeError: module 'mailgun' has no attribute 'Mailgun'

You are trying to access the 'Mailgun' class directly from the 'mailgun' module after a simple `import mailgun`, but the class needs to be imported explicitly.

fix

Use `from mailgun import Mailgun` to import the class, then instantiate it: `client = Mailgun(api_key='YOUR_API_KEY', domain='YOUR_DOMAIN')`

Upgrade

Version history

1.9.0latest on PyPI · released Aug 4, 2026

Audit

Dependencies

requestsrequiredRequired for making HTTP requests to the Mailgun API.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mailgun/mailgun-python ↗

packagehttps://pypi.org/project/mailgun/ ↗

homepagehttps://www.mailgun.com ↗

docshttps://documentation.mailgun.com ↗