# Email alerts

> Choose which problems VMYard emails you about in each organization, and how the unsubscribe link in every alert works.

VMYard can email you when something needs attention, such as a machine that couldn't be stopped or a balance that ran out. Each member chooses for themselves in each organization; until you choose, your role's default applies. In the console, open **Account** and choose **Alerts**.

## Alert types

| Type | Sent when | On by default for |
| --- | --- | --- |
| `balance_exhausted` | The organization's spendable balance first reaches zero. | Owner, Billing |
| `auto_refill_failed` | An [automatic refill](/docs/guides/automatic-refill) charge was declined, had no default payment method, or stayed unconfirmed; the alert says when refill turned itself off. | Owner, Billing |
| `machine_unresponsive` | A machine VMYard observes running is missing from its host, or isn't running there. | Owner, Admin, Operator |
| `machine_stop_failed` | A stop fails or can't be confirmed, whether manual, by auto-stop, for billing, or by idle sleep. A restart never stops its machine. | Owner, Admin, Operator |
| `snapshot_failed` | Saving a machine's disk and memory to storage fails or can't be confirmed. | Owner, Admin, Operator |
| `operation_failed` | Any operation fails or can't be confirmed, including an [internet access](/docs/guides/networking) change (the same rule as the `operation.failed` [webhook](/docs/guides/webhooks)). | Nobody; opt in |
| `auto_stop` | A machine's [auto-stop](/docs/concepts/auto-stop) deadline passed and VMYard stopped it. | Nobody; opt in |
| `billing_stop` | The balance stayed exhausted past the grace period and VMYard stopped a machine. | Nobody; opt in |
| `idle_sleep` | A machine was idle for its [idle-sleep](/docs/concepts/idle-sleep) window and VMYard put it to sleep. | Nobody; opt in |
| `abuse_stop` | A trial machine used every vCPU at full load for a long stretch, the pattern of crypto mining, and VMYard stopped it for review. | Owner, Admin, Operator |
| `disk_almost_full`, `disk_full` | A running machine's disk is at least 90% (`disk_almost_full`) or 98% (`disk_full`) used. See [Machine metrics](/docs/guides/machine-metrics#disk-warnings). | Owner, Admin, Operator |
| `product_announcements` | Not sent by VMYard yet. | Nobody; opt in |

The same type is sent at most once an hour per machine (or per organization, for balance alerts). Alerts carry machine and operation IDs, the kind of operation, its status, and its error code, never command output or request bodies. Delivery is retried for a while if the mail provider fails, and an alert more than a day old is dropped rather than sent late.

## Read and change your preferences

```sh
curl "$VMYARD_API_URL/v1/notifications/preferences" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

The answer has the `email` alerts go to and, for every type, `enabled`, `default_enabled` (your role's default), `customized` (you made a choice), `available` (VMYard sends it today), and a one-line `description`.

```sh
curl -X PUT "$VMYARD_API_URL/v1/notifications/preferences" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alerts": {"operation_failed": true, "auto_stop": false}}'
```

`PUT` changes only the types it lists and answers the whole document. An empty map or an unknown type answers `422`. Preferences are personal: any member may read and change their own, and an API key acts for the member who created it. Reading accepts every key preset; changing needs a `full_access` key or a signed-in browser session.

## Unsubscribe links

Every alert email has a link that turns off that one alert type for you in that organization, without signing in. Opening it shows a confirmation page on the VMYard API and changes nothing, so mail scanners that follow links are harmless; the page's button confirms. Mail apps that support one-click unsubscribe (RFC 8058) use the same link. Links don't expire, but they stop working if the server's operator rotates its session secret; a broken link answers `400 invalid_unsubscribe_token`. You can turn the alert back on from **Alerts** at any time.

> [!NOTE]
> An organization's server only sends email when its operator configured an email provider. Without one, alerts are recorded but not sent.