Email Providers

Overview

PushMail uses a unified provider abstraction so you can send email through any of 10 supported providers. Every provider follows the same API — create a sending config with your credentials, verify it, and you're ready to send. Events from all providers are normalized into the same format for consistent tracking.

By default, PushMail sends through a managed SendGrid account. With BYOK, you bring your own API key from any supported provider to send through your own domain and reputation.

Supported providers

Batch means the provider supports sending to multiple recipients in a single API call. Providers without batch support send one API call per recipient.

Webhooks (signature) means the provider signs webhook payloads with a cryptographic signature that PushMail verifies. Webhooks (secret) means PushMail verifies the webhook using a shared secret passed as a query parameter.

Listing providers

GET /v1/providers

Returns all supported providers with their capabilities and required configuration fields.

curl https://pushmail.dev/api/v1/providers \
  -H "Authorization: Bearer pm_live_YOUR_KEY"

{
  "data": {
    "providers": [
      {
        "name": "sendgrid",
        "displayName": "SendGrid",
        "supportsWebhooks": true,
        "supportsBatch": true,
        "configFields": [
          {
            "key": "apiKey",
            "label": "API Key",
            "type": "password",
            "required": true,
            "placeholder": "SG.xxxxxxxxxxxxxxxxxxxxxxxx",
            "helpText": "SendGrid API key with Mail Send permission"
          }
        ]
      },
      {
        "name": "ses",
        "displayName": "Amazon SES",
        "supportsWebhooks": true,
        "supportsBatch": false,
        "configFields": [
          {
            "key": "apiKey",
            "label": "Access Key ID",
            "type": "password",
            "required": true,
            "placeholder": "AKIAIOSFODNN7EXAMPLE"
          },
          {
            "key": "secretAccessKey",
            "label": "Secret Access Key",
            "type": "password",
            "required": true
          },
          {
            "key": "region",
            "label": "AWS Region",
            "type": "select",
            "required": true,
            "options": [
              { "value": "us-east-1", "label": "US East (N. Virginia)" },
              { "value": "us-west-2", "label": "US West (Oregon)" },
              { "value": "eu-west-1", "label": "EU (Ireland)" },
              { "value": "eu-central-1", "label": "EU (Frankfurt)" },
              { "value": "ap-southeast-1", "label": "Asia Pacific (Singapore)" },
              { "value": "ap-northeast-1", "label": "Asia Pacific (Tokyo)" }
            ]
          }
        ]
      }
    ]
  }
}

Use the configFields array to dynamically build credential forms in your UI. Each field includes a key, label, type, and whether it's required.

Creating a sending config

POST /v1/sending-configs

Pass your provider name, credentials, and from address. PushMail encrypts all credentials at rest.

SendGrid

curl -X POST https://pushmail.dev/api/v1/sending-configs \
  -H "Authorization: Bearer pm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "sendgrid",
    "credentials": {
      "apiKey": "SG.your-sendgrid-api-key"
    },
    "fromEmail": "hello@yourdomain.com",
    "fromName": "Your Company"
  }'

Amazon SES

curl -X POST https://pushmail.dev/api/v1/sending-configs \
  -H "Authorization: Bearer pm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "ses",
    "credentials": {
      "apiKey": "AKIAIOSFODNN7EXAMPLE",
      "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "region": "us-east-1"
    },
    "fromEmail": "hello@yourdomain.com",
    "fromName": "Your Company"
  }'

Mailgun

curl -X POST https://pushmail.dev/api/v1/sending-configs \
  -H "Authorization: Bearer pm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "mailgun",
    "credentials": {
      "apiKey": "key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "domain": "mg.yourdomain.com",
      "region": "us"
    },
    "fromEmail": "hello@yourdomain.com",
    "fromName": "Your Company"
  }'

Response

All provider configs return the same response shape. The response includes a webhookUrl and webhookSecret for providers that support webhooks.

{
  "data": {
    "id": 1,
    "orgId": 1,
    "provider": "sendgrid",
    "fromEmail": "hello@yourdomain.com",
    "fromName": "Your Company",
    "isByok": true,
    "verified": false,
    "createdAt": "2026-01-15T10:00:00.000Z",
    "webhookUrl": "https://pushmail.dev/api/v1/webhooks/sendgrid",
    "webhookSecret": "a1b2c3d4e5f6..."
  }
}

Request parameters

Verifying a config

POST /v1/sending-configs/:id/verify

Sends a test email through the provider to confirm your credentials and from address are valid.

curl -X POST https://pushmail.dev/api/v1/sending-configs/1/verify \
  -H "Authorization: Bearer pm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "you@yourdomain.com" }'

{
  "data": {
    "verified": true,
    "messageId": "abc123..."
  }
}

{
  "error": "The from address does not match a verified Sender Identity"
}

Once verified, the config's verified field is set to true. You can use unverified configs, but verification confirms everything is correctly set up.

Provider-specific setup

SendGrid

Credentials: API Key with "Mail Send" permission.

Where to get it: SendGrid Dashboard > Settings > API Keys > Create API Key.

Webhook URL: https://pushmail.dev/api/v1/webhooks/sendgrid?config_id=YOUR_CONFIG_ID

Webhook setup: In SendGrid, go to Settings > Mail Settings > Event Webhook. Set the HTTP POST URL and select the events you want to track (Delivered, Opened, Clicked, Bounced, Spam Reports, Unsubscribes). SendGrid signs payloads with an ECDSA signature that PushMail verifies automatically.

Amazon SES

Credentials: IAM Access Key ID, Secret Access Key, and AWS Region.

Where to get it: AWS IAM Console > Users > Create access key. The IAM user needs the ses:SendEmail and ses:SendRawEmail permissions. Your from address or domain must be verified in the SES Console.

Supported regions: us-east-1, us-west-2, eu-west-1, eu-central-1, ap-southeast-1, ap-northeast-1.

Webhook URL: https://pushmail.dev/api/v1/webhooks/ses?config_id=YOUR_CONFIG_ID&secret=YOUR_WEBHOOK_SECRET

Webhook setup: SES uses SNS (Simple Notification Service) for event notifications. Create an SNS topic, add an HTTPS subscription pointing to the webhook URL above, then configure a Configuration Set in SES to publish events to that topic. PushMail auto-confirms the SNS subscription.

Postmark

Credentials: Server API Token.

Where to get it: Postmark Dashboard > Servers > Your Server > Settings > API Tokens.

Webhook URL: https://pushmail.dev/api/v1/webhooks/postmark?config_id=YOUR_CONFIG_ID&secret=YOUR_WEBHOOK_SECRET

Webhook setup: In Postmark, go to Servers > Your Server > Webhooks > Add Webhook. Set the URL and select the events you want (Delivery, Bounce, Spam Complaint, Open, Click).

Mailgun

Credentials: Private API Key, Sending Domain, and Region (US or EU).

Where to get it: Mailgun Dashboard > API Security > API Keys. Your sending domain must be verified under Sending > Domains.

Extra fields:

• domain — Your verified Mailgun sending domain (e.g., mg.example.com)
• region — us (default) or eu for EU-based accounts

Webhook URL: https://pushmail.dev/api/v1/webhooks/mailgun?config_id=YOUR_CONFIG_ID

Webhook setup: In Mailgun, go to Sending > Webhooks. Add the URL for each event type (Delivered, Permanent Failure, Temporary Failure, Complained, Opened, Clicked, Unsubscribed). Mailgun signs payloads with HMAC-SHA256 using your webhook signing key.

SparkPost

Credentials: API Key with "Transmissions: Read/Write" permission.

Where to get it: SparkPost Dashboard > Configuration > API Keys.

Webhook URL: https://pushmail.dev/api/v1/webhooks/sparkpost?config_id=YOUR_CONFIG_ID

Webhook setup: In SparkPost, go to Configuration > Webhooks > Create Webhook. Set the Target URL and select the event types (Delivery, Bounce, Spam Complaint, Open, Click). SparkPost includes authentication headers that PushMail verifies.

Brevo

Credentials: API Key.

Where to get it: Brevo Dashboard > Settings > SMTP & API > API Keys.

Webhook URL: https://pushmail.dev/api/v1/webhooks/brevo?config_id=YOUR_CONFIG_ID&secret=YOUR_WEBHOOK_SECRET

Webhook setup: In Brevo, go to Settings > Webhooks > Add a New Webhook. Set the URL and select event types (Delivered, Hard Bounce, Soft Bounce, Complaint, Opened, Clicked, Unsubscribed).

Mailjet

Credentials: API Key (public key) and API Secret (private key).

Where to get it: Mailjet Dashboard > Account Settings > REST API > API Key Management.

Webhook URL: https://pushmail.dev/api/v1/webhooks/mailjet?config_id=YOUR_CONFIG_ID&secret=YOUR_WEBHOOK_SECRET

Webhook setup: In Mailjet, go to Account Settings > Event Notifications (Webhooks). Add the webhook URL for each event type (Sent, Bounce, Spam, Open, Click, Unsub, Blocked).

Mandrill (Mailchimp Transactional)

Credentials: API Key.

Where to get it: Mandrill Dashboard > Settings > SMTP & API Info.

Webhook URL: https://pushmail.dev/api/v1/webhooks/mandrill?config_id=YOUR_CONFIG_ID

Webhook setup: In Mandrill, go to Settings > Webhooks > Add Webhook. Set the Post To URL and select the event types (Send, Hard Bounce, Soft Bounce, Spam, Open, Click, Unsub, Reject). Mandrill signs payloads that PushMail verifies using your webhook key.

Resend

Credentials: API Key.

Where to get it: Resend Dashboard > API Keys > Create API Key.

Webhook URL: https://pushmail.dev/api/v1/webhooks/resend?config_id=YOUR_CONFIG_ID

Webhook setup: In Resend, go to Webhooks > Add Webhook. Set the endpoint URL and select events (email.delivered, email.bounced, email.complained, email.opened, email.clicked). Resend uses Svix for signed webhook delivery, which PushMail verifies automatically.

Elastic Email

Credentials: API Key.

Where to get it: Elastic Email Dashboard > Settings > API Keys > Create API Key.

Webhook URL: https://pushmail.dev/api/v1/webhooks/elastic-email?config_id=YOUR_CONFIG_ID&secret=YOUR_WEBHOOK_SECRET

Webhook setup: In Elastic Email, go to Settings > Notifications > Webhooks. Add the webhook URL and select event types (Sent, Error, Abuse Report, Opened, Clicked).

Webhook verification

PushMail uses two strategies for verifying incoming webhooks, depending on whether the provider natively signs its payloads.

Providers with native signatures

SendGrid, Mailgun, Mandrill, SparkPost, and Resend sign their webhook payloads using cryptographic signatures (ECDSA, HMAC-SHA256, or Svix). For these providers, use a webhook URL with just the config_id parameter:

https://pushmail.dev/api/v1/webhooks/{provider}?config_id=YOUR_CONFIG_ID

PushMail verifies the provider's signature using the webhook secret stored in your sending config.

Providers without native signatures

Brevo, Elastic Email, Mailjet, Postmark, and SES do not include cryptographic signatures on webhook payloads (or use non-standard mechanisms). For these providers, include both config_id and secret in the webhook URL:

https://pushmail.dev/api/v1/webhooks/{provider}?config_id=YOUR_CONFIG_ID&secret=YOUR_WEBHOOK_SECRET

PushMail performs a constant-time comparison of the secret query parameter against the stored webhook secret. If the secret is missing or incorrect, the webhook is rejected with a 401 status.

Managing sending configs

curl https://pushmail.dev/api/v1/sending-configs \
  -H "Authorization: Bearer pm_live_YOUR_KEY"

curl https://pushmail.dev/api/v1/sending-configs/1 \
  -H "Authorization: Bearer pm_live_YOUR_KEY"

curl -X DELETE https://pushmail.dev/api/v1/sending-configs/1 \
  -H "Authorization: Bearer pm_live_YOUR_KEY"

Using a config when sending

Pass sendingConfigId to any send endpoint to use your BYOK config instead of the managed key.

curl -X POST https://pushmail.dev/api/v1/send \
  -H "Authorization: Bearer pm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "siteId": 1,
    "templateId": 5,
    "sendingConfigId": 1
  }'

Next steps