mailgun-python：Mailgun 官方 Python SDK

mailgun-python 是 Mailgun 团队推出的官方 Python SDK，目前支持 Python 3.10 到 3.14。它把 Mailgun 的邮件发送、域名管理、事件追踪等能力，打包成一套可以直接 import 的 Python 接口。

1、 这 SDK 覆盖了什么

Mailgun 的 API 面很广。这个 SDK 几乎全包了：发邮件、管域名、配 Webhook、查事件日志、管理退信和投诉列表、操作邮件列表和模板、分配 IP 池、管理 API 密钥和用户权限。甚至还支持邮件地址验证和 InboxReady 的收件箱放置测试。

同步和异步都给了。Client 是普通阻塞调用，AsyncClient 给 asyncio 场景，两个类的接口完全一致，改个类名加个 await 就能切过去。

2、 设计上的一些取舍

SDK 底层用 requests.Session 做连接池复用。简单脚本里可以直接实例化调用，长生命周期的服务（比如 Celery worker 或 Web 服务）建议用上下文管理器 with Client(...) as client，用完自动释放 TCP 连接，避免句柄泄漏。

API 密钥在日志和异常堆栈里会被自动脱敏成 ***REDACTED***，CI 日志里打印 client 实例也不会泄露凭证。JSON payload 会在发送前自动压缩，减少大请求体的带宽占用。

路由引擎是动态的。你不需要记住 /v1、v3、v4 该调哪个，SDK 会根据你的参数自动选择正确的 API 版本。比如配 Webhook 时传了 event_types，它就自动走到 v4 多事件接口。

3、 快速上手

安装很简单：

pip install mailgun

同步发邮件：

from mailgun.client import Client

client = Client(auth=("api", "your-api-key"))
response = client.messages.create(
    data={
        "from": "sender@your-domain.com",
        "to": ["recipient@example.com"],
        "subject": "Hello",
        "text": "Testing Mailgun Python SDK",
    }
)
print(response.json())

异步版本：

import asyncio
from mailgun.client import AsyncClient

async def main():
    async with AsyncClient(auth=("api", "your-api-key")) as client:
        result = await client.messages.create(data={...})
        print(result.json())

asyncio.run(main())

高级参数直接塞进 data 字典就行，包括标签、测试模式、发送时间优化（STO）等，不需要等 SDK 更新。

4、 调试和开发体验

SDK 内置了标准库的 logging，命名空间是 mailgun.client。开 DEBUG 级别就能看到完整的请求 URL 和服务器返回的错误详情。

虽然路由是动态解析的，但 IDE 的自动补全仍然能工作。dir(client) 或者 VS Code / PyCharm 的补全列表里会列出所有可用端点。整个 SDK 也做了完整的类型标注，兼容 mypy 和 pyright。

如果调用了老的废弃接口，SDK 不会报错中断，而是继续执行并抛出一个 DeprecationWarning，告诉你该迁到哪个新端点。

5、 适合哪些人用

已经在用 Mailgun 发邮件的 Python 项目，与其手写 requests 拼接 URL 和参数，不如直接上官方 SDK。API 覆盖面全，同步异步都有，连接池和错误重试也替你管好了。

on 项目，与其手写 requests 拼接 URL 和参数，不如直接上官方 SDK。API 覆盖面全，同步异步都有，连接池和错误重试也替你管好了。