Email Service Providers

Picking a provider

Provider	Best for
SendGrid	High-volume senders, established deliverability tooling, Twilio ecosystem
Postmark	Transactional-first senders, fast transactional delivery, excellent bounce/complaint reporting
Mailgun	Developer-friendly, flexible routing, good EU infrastructure options
Resend	Modern simple API, good default deliverability, nice developer UX
SMTP	Fallback — on-prem, corporate relay, dev / staging environments without an ESP account

Capabilities

SendGrid, Postmark, Mailgun, and Resend all support bounce and complaint webhooks, open tracking, and click tracking. SMTP supports send-only — no webhooks, no bounce processing, no complaint handling.

Configuring the active provider

The active provider is selected by the CampaignCanvas.Newsletter.Provider setting in appsettings.json. Supported values are sendgrid, postmark, mailgun, resend, and smtp.

{
  "CampaignCanvas": {
    "Newsletter": {
      "Provider": "sendgrid"
    }
  }
}

If the configured alias doesn’t match any registered provider (e.g. a typo), CampaignCanvas falls back to SMTP and logs a warning. Sends still go out — they just go through the SMTP path instead.

SendGrid

Configuration

{
  "CampaignCanvas": {
    "Newsletter": {
      "Provider": "sendgrid",
      "SendGrid": {
        "ApiKey": "SG.xxxxx...",
        "ApiBaseUrl": "https://api.sendgrid.com"
      }
    }
  }
}

Webhook setup

In SendGrid, configure an Event Webhook pointing at:

POST https://your-site.com/umbraco/surface/newsletter/esp/sendgrid?secret={SHARED_SECRET}

Enable the events you want delivered (delivered, bounced, opened, clicked, unsubscribed, spam reports). Signature verification uses SendGrid’s own HMAC header.

Tracking

CampaignCanvas does its own open and click tracking (see Tracking). SendGrid’s built-in tracking is disabled in the send request to avoid double-counting.

Postmark

Configuration

{
  "CampaignCanvas": {
    "Newsletter": {
      "Provider": "postmark",
      "Postmark": {
        "ApiKey": "xxxxx-xxxxx-xxxxx",
        "ApiBaseUrl": "https://api.postmarkapp.com",
        "MessageStream": "broadcast",
        "WebhookBasicAuthUser": "",
        "WebhookBasicAuthPassword": ""
      }
    }
  }
}

Message streams

Postmark separates transactional and marketing traffic into different message streams. The default broadcaststream is used for newsletter sends. If you run transactional emails through the same Postmark server, you’ll want a separate stream for those.

Webhook setup

Configure a Webhook on the broadcast stream pointing at:

POST https://your-site.com/umbraco/surface/newsletter/esp/postmark?secret={SHARED_SECRET}

Webhook auth is HTTP Basic — configure the username and password under WebhookBasicAuthUser and WebhookBasicAuthPassword in appsettings.json.

Mailgun

Configuration

{
  "CampaignCanvas": {
    "Newsletter": {
      "Provider": "mailgun",
      "Mailgun": {
        "ApiKey": "xxxxx-xxxxx",
        "Domain": "mg.your-domain.com",
        "ApiBaseUrl": "https://api.mailgun.net",
        "WebhookSigningKey": "key-xxxxx"
      }
    }
  }
}

EU data residency

For EU data residency, set ApiBaseUrl to https://api.eu.mailgun.net. Your Mailgun account must be provisioned in the EU region for this to work.

Webhook setup

In Mailgun, configure webhooks for each event type (delivered, permanent_fail, temporary_fail, complained, unsubscribed, opened, clicked) pointing at:

POST https://your-site.com/umbraco/surface/newsletter/esp/mailgun?secret={SHARED_SECRET}

Signature verification uses the HMAC signing key from your Mailgun security settings — configure it under WebhookSigningKey.

Resend

Configuration

{
  "CampaignCanvas": {
    "Newsletter": {
      "Provider": "resend",
      "Resend": {
        "ApiKey": "re_xxxxx",
        "WebhookSecret": "whsec_xxxxx"
      }
    }
  }
}

Webhook setup

Configure a webhook in the Resend dashboard pointing at:

POST https://your-site.com/umbraco/surface/newsletter/esp/resend?secret={SHARED_SECRET}

Resend uses the Svix signature spec. Copy the whsec_... secret from the webhook configuration into Resend.WebhookSecret.

Current capabilities

Resend supports bounce, complaint, open, and click webhooks. Outbound suppression sync (pushing CampaignCanvas suppression entries to Resend’s platform suppression list) is not yet implemented for any provider.

SMTP fallback

The SMTP provider uses Umbraco’s built-in email sender. It’s a pure send path — no tracking webhooks, no bounce handling, no complaint processing.

When to use it

• On-prem / air-gapped deployments where you cannot reach an external ESP
• Corporate SMTP relays that handle deliverability concerns at a higher layer
• Local development— point at a local catch-all like Papercut or MailHog to inspect sends without dispatching real mail

Configuration

{
  "CampaignCanvas": {
    "Newsletter": {
      "Provider": "smtp",
      "Smtp": {
        "Server": "smtp.your-domain.com",
        "Port": 587,
        "Username": "smtp-user",
        "Password": "smtp-password",
        "EncryptionType": "Tls"
      }
    }
  }
}

Limitations

Because SMTP has no webhook path, the following don’t work with SMTP:

• Bounce detection (you won’t see hard vs. soft bounces)
• Automatic suppression after repeated bounces
• Complaint / spam-report tracking

Open and click tracking still work because they’re implemented in CampaignCanvas itself — the tracking pixel and click redirects don’t depend on the ESP.

Production deliverability

For production sends at any meaningful volume, use one of the dedicated ESPs (SendGrid, Postmark, Mailgun, Resend). Their bounce/complaint feedback keeps your sender reputation clean; SMTP-only sending to cold lists is a fast way to get your domain blocklisted.

Webhook security

All ESP webhooks are received at the same base path, differing only by the provider alias:

POST /umbraco/surface/newsletter/esp/{provider}?secret={SHARED_SECRET}

Two layers of verification

1. Shared secret — the secret query parameter must match the CampaignCanvas.Newsletter.WebhookSecret config value. This gates the endpoint before any parsing.
2. Provider signature— each provider verifies its own signature (SendGrid HMAC, Postmark Basic auth, Mailgun HMAC, Resend Svix). Failed signatures return a 401 without processing the payload.

Configuring the shared secret

{
  "CampaignCanvas": {
    "Newsletter": {
      "WebhookSecret": "a-long-random-string"
    }
  }
}

Generate a long random value (e.g. 32+ random characters) and include it as the ?secret= query parameter when registering the webhook URL in your ESP dashboard.

Switching providers

Changing the active provider is a config change — set Provider to the new alias and restart the app. Past campaigns, recipient rows, and event history are preserved; new sends route through the new provider.

When switching, remember to:

• Authenticate the new sender domain (SPF, DKIM) before routing production traffic
• Configure webhooks on the new provider pointing at /umbraco/surface/newsletter/esp/{new-alias}
• Retire webhooks on the old provider so you don’t double- process events