Skip to content

Mail — Email Service Configuration (SendGrid)

Last reviewed: 2026-09-17

Purpose: Sending transactional email through SendGrid — SMTP and REST API integration, authentication and key handling, deliverability configuration, and the features worth enabling.

Overview

Transactional email is triggered by user actions (sign-ups, password resets, order confirmations, notifications), as opposed to marketing campaigns. SendGrid is a cloud-based delivery platform that handles sending at scale with high deliverability, and provides: - SMTP relay service - REST API for email sending - Email templates (dynamic templates) - Delivery analytics (opens, clicks, bounces, spam reports) - Suppression management (unsubscribes, bounces) - IP reputation management

Topics Covered

  • API keys — create a restricted key (mail send only) rather than a full-access key; store it in a secret manager or environment variable, never in source control
  • Sender verification — verify a single sender address for testing, and authenticate the whole domain before going to production
  • Domain authentication — publish the CNAME records SendGrid generates so SPF and DKIM align with your domain
  • Platform integration — SMTP relay for legacy applications, the REST API v3 or an official SDK library for new code

🔐 Security note: API keys are bearer credentials. Rotate them on a schedule, scope each key to the minimum required permissions, and revoke immediately if a key is exposed.

SendGrid Integration

SMTP Configuration

Setting Value
Server smtp.sendgrid.net
Port 587 (TLS) or 465 (SSL)
Username apikey
Password Your SendGrid API key

API Usage (REST)

# Send email via SendGrid API v3
curl --request POST \
  --url https://api.sendgrid.com/v3/mail/send \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "personalizations": [{"to": [{"email": "recipient@example.com"}]}],
    "from": {"email": "sender@yourdomain.com"},
    "subject": "Hello from SendGrid",
    "content": [{"type": "text/plain", "value": "Email body text"}]
  }'

Python with sendgrid library

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

message = Mail(
    from_email='sender@yourdomain.com',
    to_emails='recipient@example.com',
    subject='Hello',
    plain_text_content='Email body'
)
sg = SendGridAPIClient('YOUR_API_KEY')
response = sg.send(message)

Email Deliverability Best Practices

  1. Authenticate your domain:
  2. SPF — Sender Policy Framework (authorized sending IPs)
  3. DKIM — DomainKeys Identified Mail (cryptographic signing)
  4. DMARC — Domain-based Message Authentication, Reporting & Conformance
  5. Warm up your sending IP — Gradually increase volume when using a new IP
  6. Monitor bounces and complaints — Remove invalid addresses, respect unsubscribe requests
  7. Use dedicated sending IPs — For high-volume senders
  8. Avoid spam triggers — No misleading subject lines, clean HTML, proper text/plain alternative

SendGrid Features

Feature Description
Dynamic Templates Handlebars-based email templates managed in SendGrid UI
Substitution Tags Personalize emails with user-specific data
Categories Track email performance by category tag
Suppression Groups Managed unsubscribe groups
Webhooks Receive real-time event data (delivered, opened, clicked, bounced)
Batch sending Send to multiple recipients with personalized content

Resources