Quiet hours

A text message to a US number may only be sent during daytime hours in the recipient’s own local time. That is a legal restriction rather than a preference, and it is enforced here rather than left to each flow author to remember: a message whose recipient’s clock is outside the window is held and sent when the window opens. This applies to SMS and to nothing else. Email carries no such restriction and has no gate — see quiet hours do not apply to email.

The window that is enforced

08:00 until 21:00, every day of the week, in the recipient’s local time. That is the federal window, and it is what the platform applies to every marketing message before it goes out. Two properties are worth knowing before you meet them: The check happens when the message is about to leave, not when the task starts. Outbound work is paced, so a message can be queued at 20:55 and reach the front of the queue at 21:10. Checking at the start of the task would have blessed that send half an hour before it happened; checking where the queue delay ends is the only place the answer is still true. A held message does not hold the queue behind it. It steps out of line into a held state with a computed release time, and the next message is sent immediately — including a transactional one, and including one addressed to a recipient three time zones away for whom it is the middle of the afternoon. One recipient’s clock never becomes everybody’s.

Working out where the recipient is

A window in the recipient’s local time needs a time zone, and a text message does not carry one. So the send task declares which parts of your record say where the recipient is, and the platform asks them in order, using the first one that answers:

{
  "action_id": "twilio__sms__send",
  "quiet_hours": {
    "lead_timezone": "{{ input.record.timezone }}",
    "zip_code": "{{ input.record.postal_code }}",
    "state": "{{ input.record.state }}"
  },
  "parameters": { "to": "{{ input.record.phone_e164 }}", "sender": "+15551234567", "body": "…" }
}

Order	Source	What it must resolve to
1	`lead_timezone`	An IANA time-zone name, such as `America/Chicago`. Used as-is when it names a zone the platform knows.
2	`zip_code`	A US ZIP code, `#####` or `#####-####`. Consulted when no usable time zone was supplied.
3	`state`	A two-letter US state abbreviation, such as `TX`. Consulted last.
4	—	Nothing resolved: the recipient’s location is unknown, and the conservative window applies.

Each one is an expression evaluated against the flow’s context, exactly like a task parameter. Supply as many or as few as your records actually carry — each is optional, and an unanswerable one simply falls through to the next.

The recipient’s phone number is deliberately not one of these sources, and it never will be. Numbers are portable and people move: an area code says where a number was issued, not where its owner is. Guessing wrong means texting somebody in the middle of their night, which is the exact outcome this whole mechanism exists to prevent — so the platform declines to guess. There is no parameter through which a number could be offered, and adding one would be a visible change rather than a quiet one.

Only the answer travels onward. The ZIP and the state stay on the record; what is carried alongside the queued message is a time-zone name and nothing else.

When a state spans two time zones

Fourteen US states span more than one zone — Florida, Texas, Michigan, Indiana, Kentucky, Alaska and eight others. A recipient resolved by state alone in one of those cannot be placed in a single zone, so they are treated as unknown and take the conservative window below. It is always the later answer, never the earlier one. Both of the other two sources are unaffected: a record carrying a time zone, or a ZIP code, resolves such a recipient precisely. If your leads are in split states and you want the full window, carry one of those.

When nothing resolves

An unknown location does not mean “send anyway” and it does not mean “fail”. It means send only during hours that are legal in every US time zone — the overlap of 08:00–21:00 across Hawaii at one end and the east coast at the other:

Season	The window, in Eastern time	In UTC
Summer (daylight saving)	14:00 – 21:00	18:00 – 01:00
Winter (standard time)	13:00 – 21:00	18:00 – 02:00

That is roughly seven hours a day, and it is much narrower than any single zone’s window. If your records carry no time zone, no ZIP and no state — or if the task declares no quiet_hours sources at all — then every marketing message you send takes this band, and most of what you queue in the morning will be held until the afternoon.Nothing is lost and nothing errors; the messages go out later the same day. But an author who expected a 13-hour window and got a 7-hour one will read it as the platform being broken, so it is worth checking one record before you send a hundred thousand.

The band is bounded at the opening end by Hawaii’s 08:00 — which is 18:00 UTC all year, since Hawaii does not observe daylight saving — and at the closing end by 21:00 on the east coast. It is computed from real time-zone rules on the day, not from a stored offset, so it is correct across both daylight-saving transitions rather than an hour wrong for a fortnight twice a year.

Marketing and transactional

Each send task declares what kind of message it sends, and that is what decides whether the window applies:

`traffic_class`	Quiet hours	What it is for
`marketing` (the default)	Applied. The message is held until the recipient’s window opens.	Anything the recipient did not specifically ask to receive at that moment.
`transactional`	Bypassed. The message is sent immediately, at any hour.	Messages the recipient asked for and is waiting on: one-time passcodes, fraud alerts, appointment and delivery notifications.

marketing is the default deliberately: it is the protected value, so it has to be the one a task gets by saying nothing about the field. The other ordering fails invisibly — nothing errors, nothing looks wrong, and the first signal is a complaint.

Declaring transactional requires an administrator. A non-admin save is refused with a 422 naming the step and the field. The declaration is recorded on the flow, so who switched off a legal protection and on which step is answerable afterwards.The vocabulary is exactly those two values. There is no account-level switch and no per-run override — a single toggle that could turn the protection off everywhere is precisely what this design rejects.

A held message

A message held for quiet hours is a first-class, visible state, not a silent pause. On the run. GET /flows/executions/{execution_id} carries a quiet_hours_hold object while the message is held:

{
  "id": "exec_84e3a014280848f4",
  "status": "running",
  "quiet_hours_hold": {
    "zone": "America/Denver",
    "hold_until": "2026-09-05T14:00:00Z"
  }
}

It is deliberately not a new execution status, and the reason is that the two facts are independent: a run can be parked on a human reply and have its next message held for legal hours at the same time. So status says whether the run is parked, and quiet_hours_hold says whether a message is waiting on a clock. The presence of the object is the whole signal — null (the overwhelmingly common case) means no legal-hours hold is in force, which is not the same as “not parked”. Two details when you read it:

zone is the time zone the window was evaluated in. null means the recipient’s location was unknown and the conservative window above is in force. It never means UTC.
The object is populated by the detail route only. The executions list leaves it out, the same way it leaves out per-step detail.

On the stream. Watching the execution stream shows the same thing as it happens:

Event	When
`execution.held_quiet_hours`	The message was held. Carries the zone and the release instant.
`execution.quiet_hours_released`	The hold ended and the message returned to the queue.

Neither is terminal, so a hold never closes an open stream — a detail view can sit on a run held overnight and pick the story back up in the morning. A held message keeps its place in line. When the window opens it returns to the queue in the position it left, ahead of everything queued behind it while it waited. Nothing is re-sent and nothing is dropped.

A release can lag the window opening by a few minutes. Holds are released as part of the ordinary dispatch cycle rather than by a clock ticking alongside it, so on an account with other work in flight a release is picked up promptly, and on an otherwise idle account it can wait up to about five minutes. This is the same behaviour a scheduled pause resume has, for the same reason.

No phone number appears anywhere in any of this — not in the hold object, not in either stream event, not in the operator logs behind them. A zone name, a release time and the run’s own identifiers are the whole of it.

Stricter state rules

Several US states impose windows narrower than the federal one, and the platform maintains a dated table of them.

The table below is published as reference. It is not what the send gate enforces today.What is applied to an outbound message is the federal 08:00–21:00 window described above, in the recipient’s resolved local time. The stricter state windows are not yet applied at the point a message is sent, because the state is deliberately not carried alongside the queued message — only the resolved time zone is, and a time zone cannot be turned back into a state.The federal window is always legal, so this is a gate that is narrower than the table, never a gate that is missing. But if your own obligations are stricter than federal — and in these states they are — you must express that yourself, with the windowed execution model on the sending step, until the gate applies the table itself.

The table is current as of 2026-09-03. These rules change, so the date is published with it rather than left implicit — a table with no as-of date is one nobody can tell is stale. A state that is absent from the table uses the federal window rather than falling into a gap.

State	Window (recipient local)	Days
AL	08:00 – 20:00	Mon–Sat
CT	09:00 – 20:00	every day
FL	08:00 – 20:00	every day
IL	09:00 – 21:00	every day
KY	10:00 – 21:00	every day
LA	08:00 – 20:00	Mon–Sat
MA	08:00 – 20:00	every day
MD	08:00 – 20:00	every day
MI	09:00 – 21:00	every day
MN	09:00 – 21:00	every day
MS	08:00 – 20:00	Mon–Sat
NM	09:00 – 21:00	every day
NV	09:00 – 20:00	every day
OK	08:00 – 20:00	every day
PA	09:00 – 21:00 Mon–Sat; 13:30 – 21:00 Sunday	every day
RI	09:00 – 18:00 Mon–Fri; 10:00 – 17:00 Saturday	Mon–Sat
SD	09:00 – 21:00	Mon–Sat
TX	09:00 – 21:00 Mon–Sat; 12:00 – 21:00 Sunday	every day
UT	08:00 – 21:00	Mon–Sat
WA	08:00 – 20:00	every day
WY	08:00 – 20:00	every day

Holiday restrictions are not covered. Six states in the table above — AL, LA, MS, PA, RI and UT — additionally restrict calling on certain public holidays. Those restrictions are not enforced by the platform and are not represented in the table. If they apply to you, handle them in your own scheduling.Nebraska is deliberately absent. The available sources contradict each other about what its rule is and whom it applies to, and a compliance table is the wrong place to record a guess — so Nebraska takes the federal window until a citable answer exists.

This is a starting point for your own compliance review and not a substitute for one. The table is maintained on a best-effort basis from public sources, most of them secondary, and it is dated for exactly that reason.

Next steps

SMS

The two send steps, both sender forms, and what a send reports.

Dispatch pacing

Why a message waits for reasons other than the clock, and what a pause holds.

Execution models

Confine a task to your own recurring local-time window, per record.

Execution streaming

Watch a run hold and release live, without polling.

Getting Started

Core Concepts

Building Flows

Triggers & Streaming

The window that is enforced

Working out where the recipient is

When a state spans two time zones

When nothing resolves

Marketing and transactional

A held message

Stricter state rules

Next steps

SMS

Dispatch pacing

Execution models

Execution streaming

​The window that is enforced

​Working out where the recipient is

​When a state spans two time zones

​When nothing resolves

​Marketing and transactional

​A held message

​Stricter state rules

​Next steps

SMS

Dispatch pacing

Execution models

Execution streaming

The window that is enforced

Working out where the recipient is

When a state spans two time zones

When nothing resolves

Marketing and transactional

A held message

Stricter state rules

Next steps