SendGrid

Warnings

• breaking v6.x is a breaking change from v5.x. The SendGridAPIClient constructor signature changed, and the send pattern via sg.client.mail.send.post() requires a raw dict, not the old Mail object's .get() call in some patterns.
  Fix: Upgrade to v6 and use Mail helper class with sg.send(message) or pass raw dict to sg.client.mail.send.post(request_body=data).
• gotcha 202 Accepted does not mean delivered. SendGrid queues emails and delivers asynchronously. Checking response.status_code == 200 will always fail — the success code is 202.
  Fix: Check response.status_code == 202 for success. Use Event Webhooks for delivery/bounce/open tracking.
• gotcha The from_email must be a verified sender (Single Sender Verification) or from a domain with Domain Authentication set up. Sending from unverified addresses returns 403 Forbidden.
  Fix: Complete Domain Authentication in SendGrid dashboard, or verify the specific sender address via Single Sender Verification.
• gotcha SendGrid Free plan was retired May 27, 2025. New accounts can no longer use the free tier after this date. Existing free accounts had 60 days before billing required.
  Fix: For free email sending, consider Resend (100/day free) or Postmark (100/month free). For existing SendGrid integrations, upgrade to a paid plan.
• gotcha SDK GitHub repository last updated September 2025. The library is in maintenance mode — new SendGrid features may not be reflected in the SDK. Use sg.client._('endpoint').post(request_body=data) for endpoints not in the helper.
  Fix: For new SendGrid features, use the low-level client: sg.client._(endpoint).method(request_body=data).

Install

• pip install sendgrid Python

Imports

• SendGridAPIClient (Mail helper)

  from sendgrid import SendGridAPIClient
  from sendgrid.helpers.mail import Mail
  
  message = Mail(
      from_email='from@example.com',
      to_emails='to@example.com',
      subject='Subject',
      html_content='<strong>Hello</strong>'
  )
  sg = SendGridAPIClient(os.environ.get('SENDGRID_API_KEY'))
  response = sg.send(message)

  sg.send(message) is the v6 shorthand. sg.client.mail.send.post(request_body=message.get()) is the older explicit pattern — both work in v6 but sg.send() is simpler.

Quickstart

202 Accepted means queued for delivery, not delivered. The from_email must be a verified sender or from a verified domain.

import os
from sendgrid import SendGridAPIClient
from sendgrid.helpers.mail import Mail

message = Mail(
    from_email='sender@example.com',
    to_emails='recipient@example.com',
    subject='Sending with SendGrid',
    html_content='<strong>Hello from Python!</strong>'
)

try:
    sg = SendGridAPIClient(os.environ.get('SENDGRID_API_KEY'))
    response = sg.send(message)
    print(response.status_code)  # 202 = accepted
except Exception as e:
    print(str(e))