{"id":4097,"library":"mailgun","title":"Python SDK for Mailgun","description":"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.","status":"active","version":"1.6.0","language":"en","source_language":"en","source_url":"https://github.com/mailgun/mailgun-python","tags":["email","API client","mailgun","async"],"install":[{"cmd":"pip install mailgun","lang":"bash","label":"Install Mailgun Python SDK"}],"dependencies":[{"reason":"Required for making HTTP requests to the Mailgun API.","package":"requests","optional":false}],"imports":[{"symbol":"Client","correct":"from mailgun.client import Client"},{"note":"Use for asynchronous applications with non-blocking I/O.","symbol":"AsyncClient","correct":"from mailgun.client import AsyncClient"}],"quickstart":{"code":"import os\nfrom mailgun.client import Client\n\ndef send_simple_message():\n    api_key = os.environ.get('MAILGUN_API_KEY', 'YOUR_MAILGUN_API_KEY')\n    domain = os.environ.get('MAILGUN_DOMAIN', 'YOUR_MAILGUN_DOMAIN')\n    # Use the appropriate API base URL for your region (US or EU)\n    # For US: api_base_url = \"https://api.mailgun.net/v3\"\n    # For EU: api_base_url = \"https://api.eu.mailgun.net/v3\"\n    api_base_url = os.environ.get('MAILGUN_API_BASE_URL', \"https://api.mailgun.net/v3\")\n\n    if not api_key or not domain:\n        print(\"Please set MAILGUN_API_KEY and MAILGUN_DOMAIN environment variables.\")\n        return\n\n    client = Client(auth=(\"api\", api_key), api_url=f\"{api_base_url}/{domain}\")\n\n    try:\n        response = client.send_message(\n            from_email=\"Excited User <mailgun@{}>.format(domain)\",\n            to_emails=[\"test@example.com\"], # Replace with a verified recipient\n            subject=\"Hello from Mailgun Python SDK\",\n            text=\"Congratulations, you just sent an email with Mailgun Python SDK!\"\n        )\n        print(f\"Mailgun API response: {response.status_code} - {response.json()}\")\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n\nif __name__ == \"__main__\":\n    send_simple_message()\n","lang":"python","description":"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."},"warnings":[{"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).","message":"Mailgun 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add and verify recipient email addresses in your Mailgun dashboard under the 'Sandbox Domains' section.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The '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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"The `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.","severity":"gotcha","affected_versions":">=1.5.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}