Markdown

Integrations

Connect third-party services used by automations, alerts and DNS workflows — Twilio for SMS steps, Slack for deliverability alerts, Cloudflare and Vercel for domain tooling, Railway for API keys and the SMTP relay, Netlify and DigitalOcean for API keys, Appwrite for account email over SMTP, Firebase for Authentication email over SMTP, and Auth0 for tenant email.

Updated Nov 17, 20268 min read

Looking for setup guides for Knock, Courier, Novu, Zapier, Make, WordPress and more? See the integration guides and the integrations hub.

Base URL: https://api.groundmail.dev

Auth: Bearer gm_… full-access API key (or dashboard session cookie). Sending-scoped keys cannot manage integrations.

Twilio (SMS)

Required before send_sms automation steps will deliver.

Get status

GET/integrations/twilio

Response (never includes raw credentials):

Terminal
GROUNDMAIL_API_KEY=gm_… npx -y --package=groundmail-cli -- groundmail integrations twilio status
JSON
{
  "twilio": {
    "connected": true,
    "hint": "aaaa",
    "connectedAt": "2026-01-01T00:00:00.000Z",
    "defaultFrom": "+15551234567",
    "messagingServiceSid": null
  }
}

Connect

PUT/integrations/twilio

Validates Account SID + Auth Token against Twilio, encrypts them at rest, and stores a default from number and/or Messaging Service SID for send_sms steps.

Or set env vars and omit flags:

Use --messaging-service-sid MG… instead of --from when you send via a Twilio Messaging Service.

Terminal
GROUNDMAIL_API_KEY=gm_… npx -y --package=groundmail-cli -- groundmail integrations twilio connect \
  --account-sid AC… \
  --auth-token … \
  --from +15551234567
Terminal
export TWILIO_ACCOUNT_SID=AC…
export TWILIO_AUTH_TOKEN=…
export TWILIO_DEFAULT_FROM=+15551234567
groundmail integrations twilio connect

npm

TypeScript
import { Groundmail } from 'groundmail'

const client = new Groundmail('gm_…')

await client.integrations.connectTwilio({
  accountSid: 'AC…',
  authToken: '…',
  defaultFrom: '+15551234567',
})

const { twilio } = await client.integrations.getTwilio()
console.log(twilio.connected)

Disconnect

DELETE/integrations/twilio
Terminal
groundmail integrations twilio disconnect

Slack (alerts)

Get deliverability alerts in a Slack channel you choose. Connect from the dashboard: open Integrations in the sidebar and choose Slack alerts, approve the Groundmail app in Slack, then pick a channel. The picker lists public channels and the private channels you have invited Groundmail to (private ones show a lock). Groundmail never reads messages.

The list is searchable. If your channel is not in it:

  • Private channel: invite the app first by typing /invite @Groundmail in the channel, then choose Refresh. The app can join public channels itself but cannot join private ones.
  • Still missing: choose Enter a channel ID instead and paste the ID (it starts with C or G, like C0123ABCD). Find it in Slack by opening the channel, clicking its name, and copying the ID at the bottom of the About tab.
  • Connected before private channels were supported: the picker shows a note to reconnect Slack. Disconnect and connect again to see private channels you have invited Groundmail to.

Groundmail posts when:

Alert When
Domain verification failed A verified sending domain keeps failing its DNS checks for a day
Domain blocklisted A verified sending domain or its main domain is added to Spamhaus DBL, SURBL or URIBL, and again when it comes off (blocklist monitoring)
Sending restricted Your account's sending is paused or suspended for deliverability
Automation run failed An automation run fails

Each message has a color bar for how urgent it is (amber for a domain problem, red for paused or suspended sending or a new blocklist listing, grey for a failed automation or a removal). It says what is wrong, quotes the error or the DNS record involved, and tells you what to do next.

Alert Buttons
Domain verification failed View DNS records opens that domain's DNS records tab; Setup guide opens the domains docs
Domain blocklisted Open the domain's Overview; Request removal opens the list's lookup and removal page
Sending paused or suspended Review your account opens your account page; Contact support emails support@groundmail.dev
Automation run failed Open automation opens that automation; Automations docs opens the automations docs

Every button is a plain link, so nothing in Slack changes your account. Domain alerts are limited to one per domain per hour. Turn any alert off, send a test message, switch channels or disconnect from the same panel.

Session cookie auth only (dashboard). Connecting Slack does not change your email webhooks; use webhooks for per-email events in your own code.

Cloudflare (DNS)

Session cookie auth only (dashboard Integrations page, Cloudflare card). For terminal DNS apply, pass CLOUDFLARE_API_TOKEN to domains apply instead, or rely on the stored dashboard token.

Vercel

Session cookie auth only (dashboard Integrations page, Vercel card).

Connect Vercel installs the Groundmail integration on your Vercel account or team. Then, from the same card:

  • Add your API key to a project: creates a sending API key and sets GROUNDMAIL_API_KEY on the project you pick, for Production, Preview and Development. Redeploy so the next build picks it up. If the project already has GROUNDMAIL_API_KEY, you're asked before it's replaced; the old key keeps working until you delete it under API keys.
  • Send from a domain on Vercel: for domains that use Vercel nameservers, adds the domain to Groundmail, writes its DNS records on Vercel and starts verification. A *.vercel.app address can't be used: only Vercel controls its DNS.

Disconnect removes the integration from your Vercel account. Instead of Connect Vercel you can paste a Vercel API token (with an optional team id). For terminal DNS apply, pass VERCEL_API_TOKEN and optional VERCEL_TEAM_ID to domains apply, or rely on the stored dashboard connection.

Get status

GET /integrations/vercel. oauth is true when connected through Connect Vercel; oauthAvailable says whether Connect Vercel is offered.

Connect with a token

PUT/integrations/vercel
JSON
{
  "apiToken": "vercel_…",
  "teamId": "team_…"
}

Projects and domains

GET /integrations/vercel/projects returns { "projects": [{ "id", "name", "framework" }], "domains": [{ "name", "vercelDns" }] }.

Set GROUNDMAIL_API_KEY on a project

POST /integrations/vercel/env with { "projectId": "prj_…", "replace": false }. Returns 409 with exists: true when the project already has the variable and replace is false. The response never includes the key's secret.

Disconnect

DELETE/integrations/vercel

Railway

Session cookie auth only (dashboard Integrations page, Railway card). Setup guide: Send email from Railway.

Connect Railway asks Railway for access to the projects you pick. Then, from the same card:

  • API key on a service: creates a sending key and sets it as GROUNDMAIL_API_KEY on a service in one environment. Railway redeploys the service.
  • SMTP relay: deploys the Groundmail SMTP relay into a project with its own sending key, for apps that only speak SMTP.

GET /integrations/railway returns { "railway": { "connected", "connectedAt", "available" } }.

GET /integrations/railway/projects returns { "projects": [{ "id", "name", "workspaceName", "services": [{ "id", "name" }], "environments": [{ "id", "name" }] }] }.

POST /integrations/railway/env with { "projectId", "environmentId", "serviceId", "replace": false }. Returns 409 with exists: true when the service already has GROUNDMAIL_API_KEY and replace is false. The response never includes the key's secret.

POST /integrations/railway/relay with { "projectId", "environmentId" }. Returns 409 when the project already has a service named smtp-relay.

DELETE /integrations/railway forgets the connection. To remove Groundmail from your Railway account, revoke it under Account → Apps in Railway.

Netlify

Session cookie auth only (dashboard Integrations page, Netlify card). Setup guide: Send email from Netlify.

Connect Netlify authorizes Groundmail on your Netlify account. Then pick a site and Groundmail creates a sending key and sets it as GROUNDMAIL_API_KEY on that site for every deploy context, optionally starting a production deploy.

GET /integrations/netlify returns { "netlify": { "connected", "connectedAt", "email", "available" } }.

GET /integrations/netlify/sites returns { "sites": [{ "id", "name", "url", "accountId", "accountName" }] }.

POST /integrations/netlify/env with { "siteId", "replace": false, "redeploy": true }. Returns 409 with exists: true when the site already has GROUNDMAIL_API_KEY and replace is false. The response never includes the key's secret.

DELETE /integrations/netlify forgets the connection. To remove Groundmail from your Netlify account, go to User settings → Applications in Netlify.

Appwrite

Session cookie auth only (dashboard Integrations page, Appwrite card). Setup guide: Send Appwrite account email.

Connect Appwrite authorizes Groundmail on the Appwrite Cloud projects you pick. Then pick a project and a sender, and Groundmail creates an SMTP credential and turns on the project's custom SMTP with it.

GET /integrations/appwrite returns { "appwrite": { "connected", "connectedAt", "available" } }.

GET /integrations/appwrite/projects returns { "projects": [{ "id", "name", "region", "endpoint" }], "senderDomains": ["…"] }.

POST /integrations/appwrite/smtp with { "projectId", "senderEmail", "senderName", "replace": false }. Returns 409 with currentHost when the project already uses another SMTP server and replace is false. The response includes the credential's name and prefix, never its password.

DELETE /integrations/appwrite revokes Groundmail's access at Appwrite and forgets it here.

DigitalOcean

Session cookie auth only (dashboard Integrations page, DigitalOcean card). Setup guide: Send email from DigitalOcean.

Connect DigitalOcean authorizes Groundmail on one DigitalOcean team, to read and update App Platform apps. Then pick an app, and Groundmail creates a sending key and sets it as an encrypted, app-level GROUNDMAIL_API_KEY, which deploys the app.

GET /integrations/digitalocean returns { "digitalocean": { "connected", "connectedAt", "teamName", "available" } }.

GET /integrations/digitalocean/apps returns { "apps": [{ "id", "name", "url", "region" }] }.

POST /integrations/digitalocean/env with { "appId", "replace": false }. Returns 409 with exists: true when the app already defines GROUNDMAIL_API_KEY and replace is false. The response never includes the key's secret.

DELETE /integrations/digitalocean revokes Groundmail's access at DigitalOcean and forgets it here.

Firebase

Session cookie auth only (dashboard Integrations page, Firebase card). Setup guide: Firebase email.

Connect Firebase signs in with Google and authorizes Groundmail on the Firebase projects your Google account can manage. Then pick a project and a sender address, and Groundmail creates an SMTP credential and turns on SMTP for the project's Authentication email with it. Templates and sender names are left as they are.

GET /integrations/firebase returns { "firebase": { "connected", "connectedAt", "available" } }.

GET /integrations/firebase/projects returns { "projects": [{ "id", "name", "projectNumber" }], "senderDomains": ["…"] }.

POST /integrations/firebase/smtp with { "projectId", "senderEmail", "replace": false }. Returns 409 with currentHost when the project already uses another SMTP server and replace is false. The response includes the credential's name and prefix, never its password.

DELETE /integrations/firebase revokes Groundmail's access at Google and forgets it here.

Auth0

Session cookie auth only (dashboard Integrations page, Auth0 card). Setup guide: Send Auth0 email.

Connect Auth0 uses a Machine to Machine application you create in Auth0, authorized for the Auth0 Management API with read:email_provider, create:email_provider and update:email_provider. Groundmail creates an SMTP credential and sets it as the tenant's email provider. The client secret is stored encrypted and is never returned.

GET /integrations/auth0 returns { "auth0": { "connected", "domain", "connectedAt", "senderEmail", "senderName" }, "senderDomains": ["…"] }.

PUT /integrations/auth0 with { "domain", "clientId", "clientSecret", "senderEmail", "senderName", "replace": false }. domain is the tenant's auth0.com domain, like acme.us.auth0.com. Returns 409 with currentProvider when the tenant already has another email provider and replace is false, and 400 when Auth0 rejects the application or it lacks a permission. The response includes the credential's name and prefix, never its password.

POST /integrations/auth0/sender with { "senderEmail", "senderName", "replace": false } changes the sender with the saved credentials. Same responses as PUT.

DELETE /integrations/auth0 forgets the saved credentials. It doesn't change the tenant's email provider; do that under Branding → Email Provider in Auth0.

Was this page helpful?