Workspace Settings

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

Safety settings and the humanizer are separate: see Safety Settings and Humanizer.

Read and change them

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

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

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:

{
  "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 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.

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.

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:

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.

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

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 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.

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: cooldown, missing_physical_address and no_consent
• Templates: {{physical_address}}
• Suppressions & Consent: the consent ledger
• Pause and resume sending: the account-wide stop