Skip to content
Norbelys
Esc
↑↓navigate↵open⌘Jpreview
On this page

Campaign settings

Change sending hours, timezone and tracking through the campaign resource.

Use the existing POST /campaigns and PATCH /campaigns/{id} operations. Sending settings do not require separate schedule, tracking or configuration endpoints.

Sending hours and timezone

{
  "timezone": "America/Bogota",
  "send_window": {
    "days": [1, 2, 3, 4, 5],
    "start": "08:00",
    "end": "17:00"
  }
}

days uses ISO weekdays: Monday is 1 and Sunday is 7. Times are local, in strict 24-hour HH:MM format. The start is inclusive and the end exclusive: at 17:00 this example stops admitting SMTP submissions. Overnight windows are rejected. Use send_window: null to allow any day/time; omitting the field in a patch preserves it.

Both the claim and final transport check enforce the campaign’s current window. Closed windows leave messages queued; they do not drop them or bypass mailbox pacing. An SMTP submission already in progress may finish. Follow-up delays count from the previous email’s acceptance and then wait for an eligible campaign window. Daily mailbox quotas still reset in UTC; the campaign timezone controls its sending window.

PostgreSQL evaluates IANA daylight-saving rules. A skipped local hour has no sending window; both occurrences of a repeated hour qualify, while message leases still prevent duplicate submission. A UTC timestamp is an instant; a timezone is an IANA name such as America/Bogota, not a fixed offset or the recipient’s browser timezone.

Workspace default

On creation, omit timezone to copy the authenticated Clerk organization’s public_metadata.timezone. Personal workspaces use the authenticated user’s metadata. The operator can set this non-secret field through Clerk’s metadata configuration:

{ "public_metadata": { "timezone": "America/Bogota" } }

Use a metadata merge when configuring Clerk, preserving its other keys. The API never takes an organization ID from this body and does not expose the other metadata fields. If the timezone key is missing or null, the default is UTC. A malformed configured timezone returns 409; an unavailable Clerk lookup returns 503. An explicit campaign timezone avoids that lookup. This is a new default integration; it does not assume that existing organizations already have the metadata key.

The resolved value is stored on the campaign and returned in its detail/list. Changing organization metadata does not move existing campaigns to another timezone. To copy the current default again, patch {"timezone":null}. To keep the saved value, omit it. This setting is common to API keys and dashboard sessions in the same workspace.

Send authored HTML without an open pixel or rewritten links:

{ "track_opens": false, "track_clicks": false }

Enable both for the campaign:

{ "track_opens": true, "track_clicks": true }

These campaign overrides apply to queued messages that have not started transport, including follow-ups with older sequence revisions. Omitted PATCH fields stay unchanged. null restores the captured sequence’s own track_opens or track_clicks setting. New campaigns default to null; sequence flags default to false. When publishing a sequence configuration, its revision captures the effective campaign flags. This also validates that open/click-based variant ranking has tracking enabled.

The first transport attempt freezes the flags together with the tracking host. Safe retries retain them, keeping the email consistent across attempts. If an override changes between rendering and the final send check, the message is released for preparation again. Campaign updates never rewrite an already sent email or its content revision.

Disabling tracking keeps the HTML MIME body and authored links. It does not create a plain-text-only MIME message, and campaign unsubscribe headers/footer remain present. Standalone HTML messages have no tracking or campaign footer. A variant preheader is optional content, not a tracking pixel; see campaign content.

Prefer reply-based variant evaluation when open/click collection is disabled. Tracking signals reflect observed events, not proof of inbox placement or human attention.

Mailbox windows

POST/PATCH /mailboxes also accepts timezone and send_window with the same shape. Mailbox timezone defaults to UTC on creation; PATCH omission preserves it. Set a mailbox’s send_window to null to remove its own window. Invalid timezones, overnight windows and malformed clocks are rejected. The sender intersects both mailbox and campaign windows at queue claim and immediately before submission. Standalone messages and sent previews obey the mailbox window too.

Pacing uses minimum_interval_seconds; assign different intervals to different mailboxes to stagger a pool. Daily limits are maximum recipient counts, shared across campaigns and direct sends, and reset in UTC. They do not guarantee a minimum number of successful deliveries. Reply stops, suppressions and provider failures remain in force.

Start later without rewriting the queue

After creating a paused campaign, PATCH the same campaign resource:

{
  "status": "Active",
  "start_at": "2026-09-28T20:00:00Z",
  "live_configuration": true
}

start_at is a campaign-wide earliest submission time. Both claiming and the final transport check enforce it, together with message dates, sender pacing and daily windows. Set it to null to remove the campaign floor. Paused campaigns remain paused until explicitly activated. An active campaign with a future start waits automatically; no scheduled job is needed to change its status.

Changing this floor updates the campaign row, not every pending message or enrollment. A message’s send_at remains its individual floor; the effective time also obeys the campaign floor. An email already in transport cannot be recalled.

Apply edits when pending messages are prepared

live_configuration defaults to false for compatibility. With true, the normal sender claim resolves the current published step revision, sender pool, profile, footer and CC/BCC before reserving quota. It preserves the assigned variant if that variant remains in the new revision; otherwise normal allocation chooses an available variant. Publication and claiming serialize on the campaign, so a concurrent claim uses a coherent revision. Changes committed after a claim apply on its next preparation, not to an in-flight attempt.

This is a live policy, not a bulk refresh command: subsequent edits need no queue rewrite. The message ID, idempotency key and captured recipient data are preserved. Once transport has started, retries keep their recorded configuration. Existing AI-generated messages also stay frozen; enabling live configuration requires published variants without AI prompts.

Existing enrollments keep their step order and position. Their later emails use the current revision when materialized, and newly calculated follow-up delays use that revision. Already-scheduled individual dates are not moved earlier. Preserve sequence/variant IDs when editing a campaign. Removing a captured step cancels its unsubmitted queued message (or fails an enrollment that can no longer materialize it); adding/reordering steps does not rebuild existing enrollment histories. New enrollments capture the new order.

The API work for these two controls is independent of queued recipient count. This is not a throughput guarantee: transport capacity still depends on replica, database and provider limits. No accepted, sent, suppressed or uncertain email is rewritten.

Was this page helpful?