Providers: How to Read This Book¶
This section is about the world on the other side of a profile — mail servers, email APIs, chat platforms, SMS gateways, alerting services — and it starts with the one idea everything else here hangs off:
You build the profile. We document the landscape.
A profile is yours: create_profile() will point the SMTP transport at any server that speaks SMTP and the Microsoft 365 transport at any tenant — nothing restricts you to services named in this documentation. The chapters that follow list popular services we have assessed against pg_relay's delivery capabilities, so you can skip the research when your provider happens to be one of them. A service being absent from these pages says nothing about whether it works; that's what Using an Unlisted Provider is for.
A guide, not a contract — the vendor owns their settings
Every hostname, port, scope, username format, endpoint, and response shape quoted for a third-party service in these pages is the vendor's, not ours — vendors own their settings, values, and behaviour, and change them without reference to this documentation. We quote today's values anyway, because being helpful is the point and a concrete starting point beats a shrug. But that is what these pages are: a starting point. The obligation to verify each value against the vendor's own current documentation sits with you, and where the two disagree, the vendor is right. What is authoritative here is our side of the mapping — the profile keys, the validation rules, and the delivery semantics.
Two chapters here are therefore not about any service at all: Your Own SMTP Server, for the very common case where the right endpoint is the Postfix relay already running on your network — no third-party service involved — and Using an Unlisted Provider, for the equally common case where your provider is regional or internal and will never appear in anyone's compatibility table. Both are first-class paths, not fallbacks.
Where this material comes from¶
These chapters parallel the notifications book in pg_relay's own documentation at pg-relay.pebbleit.com.au, and deliberately so — the two books describe the same delivery system from opposite sides of the interface contract. pg_relay's book speaks from the Processor's side: transports, wire formats, and the raw profile/message JSON its Go handlers consume. This book speaks from the side you actually call: create_profile(), send(), compose(), and — crucially — what is usable from this extension today versus what is assessed and waiting. Where a recipe appears in both books, pg_relay's version is the wire-level reference and this one is the practitioner's version; each chapter links to its counterpart.
The two kinds of "supported"¶
The distinction that this book adds, and that matters before you copy any recipe:
Email transports are self-serve. For transport = 'smtp' and 'm365', the profile JSON is the integration. Write it, validate it with validate_profile(), create it, send. Every SMTP recipe in Email Services — and any server of your own — works this way today, with no code change anywhere.
Webhook providers are curated adapters. For transport = 'webhook', this extension renders the provider-correct request body and interprets the provider's response in SQL — a deliberate security decision: the reachable code paths are a fixed, auditable set, so create_profile() only accepts a p_provider that has an adapter behind it. Four adapters ship today: slack (Slack Endpoints), resend, telnyx, and pagerduty (Resend, Telnyx, and PagerDuty). For every other webhook-reached service in these pages, the recipe documents the wire contract our adapter will implement — the assessment is done, the profile shape is settled, but you cannot select the provider until its adapter ships in a release.
Status at a glance¶
| Service | Reached through | Status |
|---|---|---|
| Your own SMTP server / internal relay | smtp |
Works today — chapter |
| Microsoft 365 / Exchange Online (Graph) | m365 |
Shipped — DBA Guide |
| Slack | webhook, provider = 'slack' |
Shipped — DBA Guide |
| Amazon SES | smtp |
Works today (SMTP credentials; REST excluded — SigV4) |
| SendGrid, Postmark, Mailgun, SMTP2GO, Resend | smtp |
Works today — Email Services |
| Gmail / Google Workspace | smtp (App Password, IP relay, or OAuth2) |
Works today — all SMTP routes, including OAuth2 (XOAUTH2); the gmail REST transport is planned (see below) |
| Exchange Online SMTP AUTH (OAuth2) | smtp (auth: "oauth2") |
Works today — XOAUTH2 |
| Azure Communication Services | smtp relay (OAuth2), acs REST |
SMTP relay works today (XOAUTH2); the acs REST transport is planned (see below) |
| Resend REST API | webhook, provider = 'resend' |
Shipped — adapter page |
| SMS — Telnyx (10 more assessed compatible) | webhook, provider = 'telnyx' |
Shipped — adapter page; assessments: SMS Providers |
| Incident alerting — PagerDuty (10 more assessed compatible) | webhook, provider = 'pagerduty' |
Shipped — adapter page; assessments: Incident Alerting |
| Mattermost, Microsoft Teams | webhook |
Assessed compatible; adapters unscheduled — Chat Platforms |
| AWS SNS, OnPage, Mailgun REST | — | Excluded — structural mismatches, explained in their chapters |
What "planned" means concretely¶
pg_relay's Processor (≥ 1.2) is ahead of this extension in two remaining places, and closing each gap is notifier-side work on this project's roadmap. (A third gap has already closed: OAuth2-authenticated SMTP — auth: "oauth2", the route to the ACS SMTP relay, Exchange Online SMTP AUTH, and OAuth2 Gmail SMTP — is now accepted by profile validation and documented with a worked example of each grant variety in SMTP Endpoints.)
- The
acsandgmailtransports (Azure Communication Services' REST API; the Gmail REST API): implemented in the Processor, buttransporthere is CHECK-constrained tosmtp/m365/webhook. Extending it is a schema-and-validation change. - Further webhook adapters (Mattermost, Teams, more SMS and alerting platforms): each is a self-contained set of SQL functions in this extension — the pattern the Slack, Resend, Telnyx, and PagerDuty adapters established — shipping on this extension's release cadence with no Processor involvement at all.
Until those land, the affected recipes are marked accordingly. Everything marked works today has no asterisk: copy the profile, substitute your values, go.
Start with Your Own SMTP Server — the chapter to read even if you'll end up on a hosted service, because everything else builds on its vocabulary.