# Workspace Settings

Source: https://molted.email/docs/workspace-settings

The workspace-wide sending settings (cooldown, postal address, marketing consent), who may change them, how a change is recorded and undone, and how to rename the workspace.

Three settings apply to your whole workspace, whatever the mailbox:

| Setting | Default | What it does |
| - | - | - |
| `cooldownMinutes` | `10` | How long the same template can't be sent again to the same recipient from the same mailbox. |
| `physicalAddress` | none | The postal address a marketing email must carry (CAN-SPAM). |
| `requireConsentForMarketing` | `false` | Whether a marketing send needs consent on file. |

Safety settings and the humanizer are separate: see [Safety Settings](https://molted.email/docs/safety-settings.md) and [Humanizer](https://molted.email/docs/humanizer.md).

## Read and change them

```
GET   https://mailbox.molted.email/v1/agent/config/settings
PATCH https://mailbox.molted.email/v1/agent/config/settings
```

```bash title="CLI"
molted settings get
molted settings update --cooldown-minutes 5
molted settings update --physical-address "123 Main St, Springfield, IL 62704"
molted settings update --require-consent-for-marketing true
```

```bash title="curl"
curl -X PATCH https://mailbox.molted.email/v1/agent/config/settings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cooldownMinutes": 5}'
```

Both routes answer with the settings as stored:

```json title="Response"
{
  "cooldownMinutes": 5,
  "physicalAddress": null,
  "requireConsentForMarketing": false
}
```

Send any of the three fields; fields you leave out stay as they are, and a body with none of them changes nothing. Reading works with any valid key. Changing needs a key that reaches every mailbox with `manage` or `admin` scope: a key limited to some mailboxes gets `403 mailbox_scope_denied`, and a key without the scope gets `403 insufficient_scope`.

MCP agents can read the same values from the `molted://policy-rules` resource, which returns `{ settings, safetySettings }`. There is no MCP tool to change them; use the CLI or the API.

### The fields

**`cooldownMinutes`** is a whole number of minutes from 0 to 1440. A value outside that range is clamped to it and a fraction is rounded, so `5000` is stored as `1440`. `0` turns the cooldown off. A value that is not a number is a `400` (`cooldownMinutes must be a number`). A send inside the window is blocked with the reason `cooldown`; see [Errors](https://molted.email/docs/errors.md#policy-engine) for the exception for replies.

**`physicalAddress`** is a string of up to 500 characters; surrounding spaces are trimmed. Pass `null` to clear it. An empty string is a `400` (`physicalAddress must not be empty; pass null to clear`), and so is anything over 500 characters. While no address is on file, a marketing send is blocked with `missing_physical_address`. Every template's `{{physical_address}}` is filled from this setting on every send path, and a marketing email that doesn't carry the address yet gets it as a footer; see [System variables](https://molted.email/docs/templates.md#system-variables).

**`requireConsentForMarketing`** is `true` or `false`; anything else is a `400`. When it is on, a marketing send to a recipient with no active consent on file is blocked with `no_consent`. Transactional templates and list broadcasts are exempt; see [Suppressions & Consent](https://molted.email/docs/suppressions.md#consent).

## Which changes an agent may make

An agent may tighten these settings and may not loosen them. The direction is worked out against what is stored now, field by field:

| Setting | An agent key may | Needs a person |
| - | - | - |
| `cooldownMinutes` | Keep it or raise it. | Lower it (including to `0`). |
| `physicalAddress` | Set it when none is on file, or send the value already stored. | Change it, or clear it with `null`, once one is on file. |
| `requireConsentForMarketing` | Turn it on. | Turn it off. |

If any field in a request loosens, nothing in the request is written. On the default `enforce` human gate the key gets `403 human_decision_required`, with `kind: "tenant-settings"`, a `decisionUrl` for a person, and `loosens` naming the fields (for example `["cooldownMinutes"]`). Send the tightening fields on their own, or hand the link to a person. In `warn` mode the call goes through with a `Molted-Deprecation: human-gate` header, and in `off` mode it simply works. See [Loosening a control](https://molted.email/docs/errors.md#loosening-a-control).

## How a person changes them

A person has no screen for these settings in the portal today. The routes a person's session can use are the same two, under the portal's prefix:

```
GET   https://api.molted.email/v1/me/settings
PATCH https://api.molted.email/v1/me/settings
```

```bash title="curl"
curl -X PATCH https://api.molted.email/v1/me/settings \
  -H "Cookie: YOUR_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{"physicalAddress": "123 Main St, Springfield, IL 62704"}'
```

They take the same body, apply the same limits and return the same settings. A signed-in person is never gated, so a loosening goes straight through. A portal session that belongs to an agent (one an agent signed up for itself) is gated like its key.

The `decisionUrl` in a `tenant-settings` refusal opens a page in the portal that explains what the agent asked for. It has no form to make the change.

## Recorded, and undoable

Every change is recorded with who made it (the person, or the API key) as a `settings.changed` event of kind `workspace_settings`. Its `before` and `after` hold the old and new value of each field that changed, under the stored names `cooldown_minutes`, `physical_address` and `require_consent_for_marketing`. The workspace's activity on Home shows it as "Changed the workspace settings", and the [audit log](https://molted.email/docs/privacy.md#other-event-types) holds the event itself.

A person can put back what an agent key changed, together with everything else that key did, from **Settings > Access**. A field someone changed again afterwards is left alone. See [Undo what an agent changed](https://molted.email/docs/undo-agent-changes.md).

## Rename the workspace

In the portal, open **Settings > Workspace**, type a new name and press **Save**. The name is what the workspace switcher and the top bar show.

- Only the workspace owner can rename it. Anyone else sees the name as plain text, and `PATCH /v1/me/workspace` answers `403`.
- The name is 1 to 60 characters after trimming, with no control or invisible formatting characters.
- A name that reads like a test fixture (it contains the word `test`, `e2e` or `smoke`) is refused with `Pick a different name.`

A rename isn't a loosening, so it is never held for a person.

## Related reading

- [Errors & policy blocks](https://molted.email/docs/errors.md): `cooldown`, `missing_physical_address` and `no_consent`
- [Templates](https://molted.email/docs/templates.md#system-variables): `{{physical_address}}`
- [Suppressions & Consent](https://molted.email/docs/suppressions.md#consent): the consent ledger
- [Pause and resume sending](https://molted.email/docs/account-pause.md): the account-wide stop