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

```bash
npm install groundmail
```

```js
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](https://docs.groundmail.dev/sdks/python). Any other language can call `POST https://api.groundmail.dev/emails` with the key: see the [API reference](https://docs.groundmail.dev/api/emails).

---

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