Update sending settings

Replace the workspace sending settings. The window start must be before its end and time zones must be IANA names (422 invalid_settings). approvalLookaheadHours (0–168, default 24 when omitted) controls how early messages for campaigns that need approval are rendered and queued; sending still happens only inside the send window and only once approved.

Before you start

Production is the default. Use development or staging only when explicitly scoped, and keep the same authorized organization throughout. Reading this guide performs no action.
Discover the current published action and validate/plan exact input before any later execution. Confirm the actual mutation and its provider/audit effects.
Required published permission: app_topolo_engage.workspace:write.
Resolve an accessible canonical Engage workspace using the current credential. Retain workspace context separately from action input; a settings response contains no workspace identifier and a fixture ID grants no access.

Effects and limits

Replaces the full sending-settings object. Required fields cannot be omitted as a patch.
windowStart must be strictly earlier than windowEnd; overnight sending windows are refused. Both use HH:MM, and windowWeekdays uses ISO days 1 Monday through 7 Sunday.
Omitting approvalLookaheadHours resets it to the application default of 24 hours; it does not retain the prior setting. An explicit value accepts 0–168 hours.
Approval look-ahead controls when campaigns that require approval may render and queue work. Actual sending still requires the send window, applicable approvals, recipient eligibility, valid seats and configured transport.
No message, runner or external provider operation is executed by this settings action. Existing delivery receipts and rendered messages are not retroactively changed.

Request

PUT /api/sending-settings

Inputs below are source-derived synthetic examples, not approval to execute. Discover resource context separately.

Input fields

Field	Required	Type and constraints
`globalDailyCap`	Yes	Whole number 1–10000.
`windowWeekdays`	Yes	Array of 1–7 weekday values, each 1–7 (Monday–Sunday). Stored weekdays are deduplicated and sorted.
`windowStart`	Yes	24-hour HH:MM clock; must be earlier than windowEnd.
`windowEnd`	Yes	24-hour HH:MM clock; must be later than windowStart.
`fallbackTimezone`	Yes	Accepted IANA time zone, 1–64 characters.
`healthWindowDays`	Yes	Whole number of days, 1–60.
`healthMinSent`	Yes	Whole number, 1–1000.
`healthMaxBounceRate`	Yes	Number from 0 through 1.
`healthMaxOptOutRate`	Yes	Number from 0 through 1.
`closeAfterDays`	Yes	Whole number of days, 1–60.
`approvalLookaheadHours`	No	Whole number 0–168; omission resets the value to 24, rather than retaining the previous setting.

Worked examples

Every request/response below is synthetic and unrun, authored from reviewed source and retained published schemas. It is not a captured local or production response. Fixture identities and timestamps authorize nothing.

Replace the complete reviewed settings

SOURCE-DERIVED SYNTHETIC UNRUN example. This is authored illustration, not a captured response, live authorization, provider result or test pass.

Request:

{
  "globalDailyCap": 75,
  "windowWeekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "windowStart": "09:00",
  "windowEnd": "17:00",
  "fallbackTimezone": "Europe/London",
  "healthWindowDays": 14,
  "healthMinSent": 20,
  "healthMaxBounceRate": 0.02,
  "healthMaxOptOutRate": 0.05,
  "closeAfterDays": 12,
  "approvalLookaheadHours": 48
}

Response illustration:

{
  "settings": {
    "globalDailyCap": 75,
    "windowWeekdays": [
      1,
      2,
      3,
      4,
      5
    ],
    "windowStart": "09:00",
    "windowEnd": "17:00",
    "fallbackTimezone": "Europe/London",
    "healthWindowDays": 14,
    "healthMinSent": 20,
    "healthMaxBounceRate": 0.02,
    "healthMaxOptOutRate": 0.05,
    "closeAfterDays": 12,
    "approvalLookaheadHours": 48,
    "updatedAt": "2026-10-20T00:00:00.000Z"
  }
}

Read all settings back. Omitted look-ahead becomes24 rather than retaining an earlier48; sending remains subject to its separate requirements.

Repeat after reconciling the retained row

SOURCE-DERIVED SYNTHETIC UNRUN example. This is authored illustration, not a captured response, live authorization, provider result or test pass.

Request:

{
  "globalDailyCap": 75,
  "windowWeekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "windowStart": "09:00",
  "windowEnd": "17:00",
  "fallbackTimezone": "Europe/London",
  "healthWindowDays": 14,
  "healthMinSent": 20,
  "healthMaxBounceRate": 0.02,
  "healthMaxOptOutRate": 0.05,
  "closeAfterDays": 12,
  "approvalLookaheadHours": 48
}

Response illustration:

{
  "settings": {
    "globalDailyCap": 75,
    "windowWeekdays": [
      1,
      2,
      3,
      4,
      5
    ],
    "windowStart": "09:00",
    "windowEnd": "17:00",
    "fallbackTimezone": "Europe/London",
    "healthWindowDays": 14,
    "healthMinSent": 20,
    "healthMaxBounceRate": 0.02,
    "healthMaxOptOutRate": 0.05,
    "closeAfterDays": 12,
    "approvalLookaheadHours": 48,
    "updatedAt": "2026-10-20T00:01:00.000Z"
  }
}

Read all settings back. Omitted look-ahead becomes24 rather than retaining an earlier48; sending remains subject to its separate requirements.

Omit look-ahead and observe default24

SOURCE-DERIVED SYNTHETIC UNRUN example. This is authored illustration, not a captured response, live authorization, provider result or test pass.

Request:

{
  "globalDailyCap": 75,
  "windowWeekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "windowStart": "09:00",
  "windowEnd": "17:00",
  "fallbackTimezone": "Europe/London",
  "healthWindowDays": 14,
  "healthMinSent": 20,
  "healthMaxBounceRate": 0.02,
  "healthMaxOptOutRate": 0.05,
  "closeAfterDays": 12
}

Response illustration:

{
  "settings": {
    "globalDailyCap": 75,
    "windowWeekdays": [
      1,
      2,
      3,
      4,
      5
    ],
    "windowStart": "09:00",
    "windowEnd": "17:00",
    "fallbackTimezone": "Europe/London",
    "healthWindowDays": 14,
    "healthMinSent": 20,
    "healthMaxBounceRate": 0.02,
    "healthMaxOptOutRate": 0.05,
    "closeAfterDays": 12,
    "approvalLookaheadHours": 24,
    "updatedAt": "2026-10-20T00:00:00.000Z"
  }
}

Read all settings back. Omitted look-ahead becomes24 rather than retaining an earlier48; sending remains subject to its separate requirements.

Restore separately reviewed previous values

SOURCE-DERIVED SYNTHETIC UNRUN example. This is authored illustration, not a captured response, live authorization, provider result or test pass.

Request:

{
  "globalDailyCap": 75,
  "windowWeekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "windowStart": "09:00",
  "windowEnd": "17:00",
  "fallbackTimezone": "Europe/London",
  "healthWindowDays": 14,
  "healthMinSent": 20,
  "healthMaxBounceRate": 0.02,
  "healthMaxOptOutRate": 0.05,
  "closeAfterDays": 12,
  "approvalLookaheadHours": 48
}

Response illustration:

{
  "settings": {
    "globalDailyCap": 75,
    "windowWeekdays": [
      1,
      2,
      3,
      4,
      5
    ],
    "windowStart": "09:00",
    "windowEnd": "17:00",
    "fallbackTimezone": "Europe/London",
    "healthWindowDays": 14,
    "healthMinSent": 20,
    "healthMaxBounceRate": 0.02,
    "healthMaxOptOutRate": 0.05,
    "closeAfterDays": 12,
    "approvalLookaheadHours": 48,
    "updatedAt": "2026-10-20T00:00:00.000Z"
  }
}

Read all settings back. Omitted look-ahead becomes24 rather than retaining an earlier48; sending remains subject to its separate requirements.

Refuse a semantically invalid policy or window

SOURCE-DERIVED SYNTHETIC UNRUN example. This is authored illustration, not a captured response, live authorization, provider result or test pass. Full source-derived semantic error body; not captured or executed.

Request:

{
  "globalDailyCap": 75,
  "windowWeekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "windowStart": "17:00",
  "windowEnd": "09:00",
  "fallbackTimezone": "Europe/London",
  "healthWindowDays": 14,
  "healthMinSent": 20,
  "healthMaxBounceRate": 0.02,
  "healthMaxOptOutRate": 0.05,
  "closeAfterDays": 12,
  "approvalLookaheadHours": 48
}

Response illustration:

{
  "error": {
    "code": "invalid_settings",
    "message": "The send window must start before it ends."
  }
}

Correct and approve a complete replacement before retrying; no provider/send action is triggered.

Verify the result

Read sending.settings.get with the same credential, organization and workspace and compare every supplied field.
Check approvalLookaheadHours explicitly, especially when it was omitted. Review the retained current settings before any separately authorized runner or send operation.

Errors and recovery

422 invalid_action_input: Correct the full input using the published schema. HH:MM clocks and explicit nullable fields are required where declared. Validate the corrected request before planning it.
422 invalid_settings: Correct the IANA fallbackTimezone and the strictly increasing same-day window; preserve the retained settings until the corrected full request is validated and approved.
403 permission_denied: Stop. The current credential lacks workspace:write for Engage. Do not switch context or broaden permission automatically.
403 organization_required: Stop and establish the intended authorized organization context. Never add an organization ID to the action input to bypass this refusal.
409 workspace_required: Discover an accessible canonical Engage workspace through the current credential. A fixture workspace ID grants no access and a body field cannot provision a workspace.

After an uncertain response, inspect sending.settings.get before retrying. A full replacement is safe to repeat only after verifying the retained state and concurrent changes. To restore prior settings, validate and plan the complete previously retained settings object through this same action, include the intended approvalLookaheadHours explicitly, and read back. This cannot undo messages already sent by separate runner work.

Evidence and change log

2026-10-20: Prepared this paired guide from source 767d2d83713809e984559eee562a2c9f7ffcfa4d and the retained production contract snapshot. The source/content review is recorded separately. These examples remain synthetic and unrun; no original response capture or current business-runtime behavior is claimed.
2026-10-20: First production publication verified after independent source/content review. Removed duplicate introduction and authoring-only status notes; clarified field constraints. Examples remain synthetic and unrun.