# Send Apprise alerts with Groundmail

[Apprise](https://github.com/caronc/apprise) is the notification library behind alerts in many self-hosted apps, such as backup tools, uptime monitors and media servers. It has a built-in `groundmail://` service, so any app that takes an Apprise URL can send its alerts as email through Groundmail.

---

## Prerequisites

- A Groundmail account and an API key (`gm_…`) from **API keys**.
- Apprise with Groundmail support. The `groundmail://` service is in Apprise releases after 2.1.0. Until that release is out, install Apprise from GitHub:

```bash
pip install git+https://github.com/caronc/apprise.git
```

Apps that bundle Apprise (for example in a Docker image) get Groundmail support when they update to that Apprise release.

---

## The Groundmail URL

```
groundmail://{apikey}:{from_email}
groundmail://{apikey}:{from_email}/{to_email}
groundmail://{apikey}:{from_email}/{to_email1}/{to_email2}
```

| Part | Value |
|------|-------|
| `apikey` | Your Groundmail API key |
| `from_email` | The sender address (see below) |
| `to_email` | Who gets the alert. Leave it out to send to the `from_email` address |

Optional query settings: `?name=` (sender name), `?cc=`, `?bcc=` and `?reply=` (Reply-To). Separate several addresses with commas.

### Alerts to yourself: no domain needed

Most app alerts go to the person who runs the app. Groundmail lets you send to your own account email from `noreply@mail.groundmail.dev` without verifying a domain:

```
groundmail://gm_xxx:noreply@mail.groundmail.dev/you@example.com
```

`you@example.com` must be the email address on your Groundmail account.

### Alerts to anyone: use your domain

To send to other people, such as your team or an on-call address, [verify a domain](https://docs.groundmail.dev/domains) and add a payment method under **Settings → Billing** (the free plan isn't charged). Then send from an address on that domain:

```
groundmail://gm_xxx:alerts@mail.yourdomain.com/ops@yourdomain.com?name=Backups
```

---

## Send a test

From the command line:

```bash
apprise -vv -t "Test alert" -b "Apprise is sending through Groundmail." \
  "groundmail://gm_xxx:noreply@mail.groundmail.dev/you@example.com"
```

In an app, paste the same URL wherever it asks for an Apprise or notification URL, then use its test button. Each alert appears under **Emails** in Groundmail with its delivery status.

---

## Troubleshooting

- **"Unsupported URL" or "groundmail is not a supported schema":** the Apprise version is older than the Groundmail service. Update Apprise (see Prerequisites).
- **Nothing arrives at another address:** without a verified domain and a payment method, Groundmail only delivers to your account email. Check the email's status under **Emails**.
- **401 or "invalid API key":** check the key in **API keys** and that it has permission to send.

See Apprise's own [Groundmail page](https://appriseit.com/services/groundmail/) for every URL option.