Settings API

The tunable knobs an agent may turn: the named durations flows reference, the send windows that gate when scheduled email goes out, the mailing address email footers show, and the unsubscribe page — its text and where it sends people. How emails look is a theme, not a setting. Credentials are never here.

Method & path	What it does
`GET /api/v1/settings`	The writable settings and their current values.
`PATCH /api/v1/settings`	Update any of them. Partial: only the keys you send change. Values are shape-checked before anything is stored.

The writable keys

Key	What it is
`tunables`	Named durations flows reference by name — `{ "quiet_buffer_days": { "amount": 40, "unit": "days" } }`. Units: minutes, hours, days, weeks.
`send_windows`	When scheduled sends are allowed out. Format below.
`sending.mailing_address`	The physical mailing address `{{ mailing_address }}` resolves to in email footers, as one string. Anti-spam law requires one in every marketing email; a P.O. box works. Stored stripped of surrounding whitespace.
`sending.unsubscribe_page_url`	A custom URL people are sent to right after Mimeo's unsubscribe page unsubscribes them. Blank (the default) means they stay on Mimeo's page, which offers a resubscribe button. A full `http(s)` URL sends them on, with the signed token appended as `?token=…` or dropped into a `{token}` placeholder. Anything that isn't a full URL is refused; blank clears it.
`sending.unsubscribe_page.status` `.headline` · `.confirmation` `.button_text` · `.button_color` · `.hint`	What Mimeo's page says once someone is unsubscribed: the status line, headline, confirmation text (`{email}` becomes the person's address), the resubscribe button's text and hex color, and the small text under the button. Each has a default (Done / You're unsubscribed. / {email} won't get any more email from us. / Resubscribe / the design system's accent / Clicked by mistake? This puts you back.); blank restores it. Text is stored stripped; a color that isn't hex is refused.
`sending.unsubscribe_page.resubscribed_status` `.resubscribed_headline` `.resubscribed_confirmation` `.resubscribed_button_text` `.resubscribed_hint`	The same for what the page says after the resubscribe button is pressed. Defaults: Welcome back / You're subscribed again. / {email} will keep getting email from us. / Unsubscribe / Changed your mind again? One click and you're out.

These are the same keys settings.yml carries in a definitions repo — the API, MCP and a repo push all write the same settings through the same checks.

The send-window rule format

PATCH /api/v1/settings
{ "settings": { "send_windows": { "rules": [
  { "label": "pitch", "days": [1, 2, 3, 4], "start": "11:00", "end": "15:00" },
  { "label": null,    "days": [1, 2, 3, 4, 5], "start": "09:00", "end": "17:00" }
] } } }

Key	Meaning
`label`	Scope the rule to emails carrying this label. `null`, or omitted, makes it the global rule.
`days`	Weekday numbers, 0–6 with Sunday as 0. Required, and at least one.
`start` / `end`	`"HH:MM"` on a 24-hour clock. Omitted, they default to `"00:00"` and `"24:00"`; `"24:00"` closes the day. `start` must be before `end`.

Rules are optional and additive: with none configured, everything sends the moment it comes due. Exactly one rule applies to any given email — the first whose label the email carries, else the first global rule. Times are evaluated in the account's timezone (the profile timezone setting, Eastern Time if none is set), so "9–5" means 9–5 on your own clock. An email due outside its window isn't dropped or rushed: it's held with its due time moved to the next open slot, visible in the queue as “Outside its send window”.

Errors

Status	When
`401`	Missing or revoked token.
`422`	A key that isn't writable — credentials and secrets are entered on the Settings page and stay in the instance — or a malformed value. The message names the exact problem rather than storing something that would quietly hold sends.

Over MCP, get_settings and save_settings take the same contract, and a settings.yml push through the definitions endpoints runs the same checks — a malformed rule blocks the plan with setting_invalid.