# 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.

Looking for setup guides for Knock, Courier, Novu, Zapier, Make, WordPress and more? See the [integration guides](https://docs.groundmail.dev/integrations/zapier) and the [integrations hub](https://groundmail.dev/integrations/).

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`

```bash
GROUNDMAIL_API_KEY=gm_… npx -y --package=groundmail-cli -- groundmail integrations twilio status
```

Response (never includes raw credentials):

```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.

```bash
GROUNDMAIL_API_KEY=gm_… npx -y --package=groundmail-cli -- groundmail integrations twilio connect \
  --account-sid AC… \
  --auth-token … \
  --from +15551234567
```

Or set env vars and omit flags:

```bash
export TWILIO_ACCOUNT_SID=AC…
export TWILIO_AUTH_TOKEN=…
export TWILIO_DEFAULT_FROM=+15551234567
groundmail integrations twilio connect
```

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

### npm

```ts
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`

```bash
groundmail integrations twilio disconnect
```

---

## Slack (alerts) {#slack}

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](https://docs.groundmail.dev/domains#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](https://docs.groundmail.dev/domains) |
| 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](https://docs.groundmail.dev/automations) |

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](https://docs.groundmail.dev/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`](https://docs.groundmail.dev/domains) instead, or rely on the stored dashboard token.

---

## Vercel {#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`](https://docs.groundmail.dev/domains), 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 {#railway}

Session cookie auth only (dashboard **Integrations** page, **Railway** card). Setup guide: [Send email from Railway](https://docs.groundmail.dev/integrations/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 {#netlify}

Session cookie auth only (dashboard **Integrations** page, **Netlify** card). Setup guide: [Send email from Netlify](https://docs.groundmail.dev/integrations/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 {#appwrite}

Session cookie auth only (dashboard **Integrations** page, **Appwrite** card). Setup guide: [Send Appwrite account email](https://docs.groundmail.dev/integrations/appwrite).

**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 {#digitalocean}

Session cookie auth only (dashboard **Integrations** page, **DigitalOcean** card). Setup guide: [Send email from DigitalOcean](https://docs.groundmail.dev/integrations/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 {#firebase}

Session cookie auth only (dashboard **Integrations** page, **Firebase** card). Setup guide: [Firebase email](https://docs.groundmail.dev/integrations/firebase).

**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 {#auth0}

Session cookie auth only (dashboard **Integrations** page, **Auth0** card). Setup guide: [Send Auth0 email](https://docs.groundmail.dev/integrations/auth0).

**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.
