# Change mail settings

URL: https://heaven.dev/docs/reference/computers/mail
Updated: 2026-11-21

Change a Computer's incoming mail settings or choose who it can send mail to. Turning receiving off refuses incoming mail, permanently deletes reply threads and unsubscribes everyone allowed to write to the Computer.

`POST /v1/computer/modify`

## Parameters

- `computer` (string, required): Computer name or ID.
- `state` (string): Set `on` to accept incoming mail or `off` to refuse it, delete reply threads and unsubscribe senders. Omit to keep the current setting.
- `reply_policy` (string): Mail recipients: known allows the owner, organization members and people with access. With receiving on, all also allows subscribers and replies to mail received in the last 30 days. owner allows only the owner; none blocks sending. Omission keeps the current policy.
- `dry_run` (boolean): Preview the change without applying it.

## Returns

- `data` (object, always present): The Computer's receiving and reply settings. A preview of the requested change.
  - `alternative-1` (object): The Computer's receiving and reply settings.
    - `note` (string): Effects of disabling mail reception, returned for that change. May be omitted.
    - `receiving_enabled` (boolean, always present): Whether mail reception is enabled for this Computer.
    - `receiving_reason` (string): Why receiving is disabled or unavailable, when applicable. May be omitted.
    - `reply_policy` (string, always present): Permitted reply recipients. Values: `"all"`, `"known"`, `"none"`, `"owner"`.
    - `sending_suspended` (boolean, always present): Whether outgoing mail is suspended.
  - `alternative-2` (object): A preview of the requested change.
    - `changes` (string[]): Proposed effects and losses. May be omitted.
    - `dry_run` (boolean, always present): True for a preview; no changes are made.
    - `message` (string, always present): What the request would do.

## Errors

Each code is explained in full at https://heaven.dev/docs/reference/errors.

| Code | Status | What happened |
|---|---:|---|
| `invalid` | 400 | An input is missing or invalid. |
| `unauthenticated` | 401 | The credential is missing, invalid, expired or revoked. |
| `denied` | 403 | The caller lacks permission for this action. |
| `not_found` | 404 | The resource is absent or inaccessible to this caller. |
| `conflict` | 409 | The request conflicts with the current resource state or an earlier request. |
| `over_capacity` | 409 | The request exceeds a resource or credential allowance. |
| `access_list_full` | 409 | The change would exceed the access-list allowance. |
| `payment_required` | 402 | Payment or credit is required. |
| `rate_limited` | 429 | The caller's request rate exceeds its limit. |
| `busy` | 429 | Too much work is in progress to accept this request. |
| `unknown` | 503 | The outcome is unconfirmed; a change may have happened. |
| `unavailable` | 503 | The service or requested feature is unavailable. |

## Notes

- API key permission: `mail`.

## Examples

```sh tab="heaven CLI"
heaven mail COMPUTER [on|off]
  [--reply-policy REPLY-POLICY]
  [--dry-run]
```

```sh tab="SSH"
ssh cli@heaven.dev mail COMPUTER [on|off]
  [--reply-policy REPLY-POLICY]
  [--dry-run]
```

```sh tab="cURL"
curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "mail", "computer": "my-site", "state": "on"}'
```

```json tab="MCP"
{ "tool": "mail",
  "arguments": { "computer": "my-site", "state": "on" } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "receiving_enabled": true,
    "reply_policy": "all",
    "sending_suspended": false
  }
}
```
