sendgrid-python：用 Python 调用 SendGrid 邮件 API

sendgrid-python 在 GitHub 上已经拿到 1,628 Star。

这是 Twilio SendGrid 官方维护的 Python SDK，作用很明确：让你在 Python 项目里直接调用 SendGrid Web API v3，完成邮件发送、入站邮件处理以及其他 API 操作。

1、这项目是干嘛的

如果你需要在 Python 应用里发邮件，又不想自己拼装 SMTP 请求或者处理复杂的邮件协议，这个库可以省掉很多麻烦。

它封装了 SendGrid v3 的全部接口，核心就是围绕 /mail/send 端点提供的一组 Helper，同时也支持直接访问其他 v3 端点。开发者可以用两种方式使用它：一种是直接构造 JSON 请求体，另一种是调用库内置的 Mail 辅助类。

除了发邮件，它还提供了 Inbound Parse 的辅助模块，用来处理接收到的邮件。对于需要把邮件接收和解析自动化的场景，这个模块能减少很多重复代码。

项目的依赖很少，主要包括 Python-HTTP-Client 和 Cryptography，安装过程不会拖进一堆用不上的包。

2、安装和配置

安装命令很简单：

pip install sendgrid

环境要求不高，Python 2.7 及以上版本都可以运行。如果你正在维护一个比较老的项目，也不用担心兼容性问题。

使用前需要设置 SENDGRID_API_KEY。Mac 或 Linux 环境下可以执行：

echo "export SENDGRID_API_KEY='YOUR_API_KEY'" > sendgrid.env
echo "sendgrid.env" >> .gitignore
source ./sendgrid.env

Windows 下则用 set 或 setx 命令写入环境变量。项目也支持 .env 文件，复制 .env_sample 后填入 key 即可。

3、发一封邮件有多简单

用 Mail 辅助类只需要几行代码：

import sendgrid
import os
from sendgrid.helpers.mail import *

sg = sendgrid.SendGridAPIClient(api_key=os.environ.get('SENDGRID_API_KEY'))
from_email = Email("test@example.com")
to_email = To("test@example.com")
subject = "Sending with SendGrid is Fun"
content = Content("text/plain", "and easy to do anywhere, even with Python")
mail = Mail(from_email, to_email, subject, content)
response = sg.client.mail.send.post(request_body=mail.get())
print(response.status_code)
print(response.body)
print(response.headers)

如果你不想用辅助类，也可以直接传 JSON：

import sendgrid
import os

sg = sendgrid.SendGridAPIClient(api_key=os.environ.get('SENDGRID_API_KEY'))
data = {
  "personalizations": [
    {
      "to": [{"email": "test@example.com"}],
      "subject": "Sending with SendGrid is Fun"
    }
  ],
  "from": {"email": "test@example.com"},
  "content": [
    {"type": "text/plain", "value": "and easy to do anywhere, even with Python"}
  ]
}
response = sg.client.mail.send.post(request_body=data)
print(response.status_code)

两种方式返回的结果都包含状态码、响应体和响应头，便于你做后续判断。

4、不止能发邮件

这个 SDK 同时支持 SendGrid v3 的其他端点，比如查询退信列表：

import sendgrid
import os

sg = sendgrid.SendGridAPIClient(api_key=os.environ.get('SENDGRID_API_KEY'))
response = sg.client.suppression.bounces.get()
print(response.status_code)
print(response.body)
print(response.headers)

它提供了 Fluent 风格的调用链，也支持用字符串路径直接访问 API。这意味着你既可以用 sg.client.suppression.bounces.get() 这种链式写法，也可以用 sg.client._("suppression/bounces").get() 这种更直接的方式。对于习惯了 RESTful 路径的开发者来说，第二种写法可能更容易对应到官方文档的接口说明。

项目在持续维护中，更新记录和发布信息都写在了 CHANGELOG 里。遇到问题时可以先查看自带的 TROUBLESHOOTING 文档，常见问题基本都有覆盖。

5、适合哪些人用

• 需要在 Python 后端集成邮件通知的开发者
• 正在使用 SendGrid 服务、希望减少 HTTP 请求拼装工作的团队
• 需要处理入站邮件解析的运维或开发人员

项目采用 MIT 协议，有完整的文档、示例代码和故障排查指南。整体来看，sendgrid-python 的定位很清晰：它不是要做一个大而全的邮件框架，而是把 SendGrid API 的调用成本降到最低，让你几行代码就能把邮件能力接进 Python 项目。

文档、示例代码和故障排查指南。整体来看，sendgrid-python 的定位很清晰：它不是要做一个大而全的邮件框架，而是把 SendGrid API 的调用成本降到最低，让你几行代码就能把邮件能力接进 Python 项目。