Migrate from SendGrid

Get your Postkit API key

Sign up at app.postkit.eu and create an API key in Settings > API Keys. Production keys start with pk_live_. For testing the migration without sending real emails, create a sandbox key starting with pk_test_.

Update base URL and auth

Change your base URL from SendGrid's v3 API to Postkit's v1 API, and replace your SG. key with a pk_live_ key.

Before (SendGrid):

curl -X POST https://api.sendgrid.com/v3/mail/send \
  -H "Authorization: Bearer SG.abc123..."

After (Postkit):

curl -X POST https://api.postkit.eu/v1/emails \
  -H "Authorization: Bearer pk_live_abc123..."

Flatten your send request

This is the biggest change. SendGrid uses nested personalizations arrays, while Postkit uses a flat structure.

Before (SendGrid):

{
  "personalizations": [
    {
      "to": [{ "email": "user@example.com", "name": "User" }],
      "subject": "Hello from SendGrid"
    }
  ],
  "from": { "email": "you@yourdomain.com", "name": "You" },
  "content": [
    { "type": "text/html", "value": "<h1>Hello</h1>" }
  ]
}

After (Postkit):

{
  "from": "You <you@yourdomain.com>",
  "to": ["user@example.com"],
  "subject": "Hello from Postkit",
  "html": "<h1>Hello</h1>"
}

Key structural differences:

• from is a string ("Name <email>" format), not an object
• to is a flat array of email strings, not nested inside personalizations
• subject is a top-level field, not inside personalizations
• html and text replace the content array

Update webhook verification

SendGrid uses ECDSA (asymmetric) webhook signing with a public key. Postkit uses HMAC-SHA256 (symmetric) with a shared secret prefixed whsec_.

Replace your ECDSA verification code with HMAC-SHA256 verification. Postkit sends three headers with each webhook delivery: webhook-id, webhook-timestamp, and webhook-signature.

See the Webhooks guide for complete verification examples and the signing algorithm details.

Consolidate suppression endpoints

SendGrid uses separate endpoints for each suppression type (/suppression/bounces, /suppression/blocks, /suppression/spam_reports). Postkit unifies all suppressions under a single endpoint with optional filtering.

# SendGrid -- separate endpoints per type
GET /v3/suppression/bounces
GET /v3/suppression/blocks
GET /v3/suppression/spam_reports

# Postkit -- unified endpoint with reason filter
GET /v1/suppressions
GET /v1/suppressions?reason=hard_bounce
GET /v1/suppressions?reason=complaint

Verify your domain

Add your sending domain in Postkit and configure the DNS records. Unlike SendGrid where domain verification happens automatically after DNS setup, Postkit uses an explicit verification step.

See the Domain Setup guide for step-by-step DNS configuration instructions.

Test with sandbox keys

Use a pk_test_ key to verify your integration end-to-end without delivering actual emails. Once everything works as expected, switch to your pk_live_ key for production.