Send email from DigitalOcean

Send transactional email from an app on DigitalOcean App Platform, or from a Droplet, with the Groundmail API. Your code reads the API key from the GROUNDMAIL_API_KEY environment variable.

Prerequisites

• A Groundmail account with a verified sending domain. A subdomain such as mail.yourdomain.com works well.
• An app on App Platform, or a Droplet.

Connect DigitalOcean (App Platform)

1. In the dashboard, open Integrations → DigitalOcean and click Connect DigitalOcean.
2. DigitalOcean asks you to pick a team and authorize Groundmail. Groundmail asks only to read and update App Platform apps and to read, add and change DNS records.
3. Back in Groundmail, pick an app and click Add GROUNDMAIL_API_KEY. Groundmail creates a sending key and sets it as an encrypted, app-level variable available at build and run time. Saving the variable deploys the app.

If the app already has GROUNDMAIL_API_KEY, at the app level or on a component, Groundmail asks before replacing it, and the new app-level value replaces the component ones. The key never appears on screen. It's listed under API keys as "DigitalOcean: app name", where you can revoke it.

One connection covers one DigitalOcean team. Disconnect revokes Groundmail's access; apps you already set up keep their key.

By hand

Create an API key under API keys, then in DigitalOcean open the app's Settings → App-Level Environment Variables, add GROUNDMAIL_API_KEY with the key as its value, tick Encrypt, and save.

Set up your domain's DNS

If your sending domain's DNS is on DigitalOcean (Networking → Domains), the same connection writes its records:

1. Add the domain under Domains.
2. On its DNS tab, click Apply DNS (DigitalOcean). Groundmail adds the SPF, DKIM, DMARC and return-path records, merging into an existing SPF record, then checks them.

Connections made before DNS support only cover App Platform apps. If the DigitalOcean card says Reconnect, click Connect DigitalOcean again and approve the DNS access.

Send an email

npm install groundmail

import { Groundmail } from 'groundmail'

const groundmail = new Groundmail(process.env.GROUNDMAIL_API_KEY)

await groundmail.emails.send({
  from: 'App <no-reply@mail.yourdomain.com>',
  to: 'user@example.com',
  subject: 'Reset your password',
  html: '<p>Click the link to reset your password.</p>',
})

Python, Go, PHP and Ruby have SDKs too: see SDKs. Any other language can call POST https://api.groundmail.dev/emails with the key: see the API reference.

Sending over SMTP from a Droplet

DigitalOcean blocks outbound SMTP on ports 25, 465 and 587 on Droplets. If your app can only send over SMTP, use Groundmail's SMTP relay on port 2525, which isn't blocked: host smtp.groundmail.dev, port 2525, STARTTLS, username groundmail and an SMTP credential from SMTP as the password. See SMTP.