Skip to main content

​
Recipient timezone resolution for quiet hours

Every quiet-hours decision — org gate, campaign fallback window, TCPA voice guard — is computed against the recipient’s local clock. That means the whole posture stands or falls on one question: which IANA timezone did the platform use for this recipient? The individual guides each cover a slice of the answer. This page is the single map: the resolution chain step by step, what happens when it resolves nothing, and every surface you can steer it with.

​
The resolution chain, step by step

Resolution runs fewer steps than there are channels, but each step is the same for every channel. First match wins: A relocated US mobile number resolves by its area code, not by where the recipient sleeps — if your CRM carries better knowledge, override it at step 1 rather than relaxing the policy at step 5.

​
A worked example per step

Step 1 — explicit hint. A Nevada recipient you know lives in Pacific time: pass recipientTimezone=America/Los_Angeles (send path) or timezone_override=America/Los_Angeles (preview), and the preview’s local_timezone echoes exactly that. Step 2 — NANP area code. +12125551234 → area code 212 → America/New_York. Most US recipients resolve here with no hint. Step 3 — country prefix. +442012345678 → country code +44 → Europe/London. Most European recipients resolve here. Step 4 — org default. An email recipient with no phone number resolves to your org’s settings.timezone — say America/Chicago — so email quiet hours follow your organization’s clock without per-recipient hints. Step 5 — unresolved. A toll-free +1800 number carries no geographic signal; an email recipient on an org with no default timezone has none either. Both land on unknown_timezone_policy — the decision tree below.

​
The NANP area-code map specifics

For +1 numbers, the map carries every currently assigned geographic area code — the continental US, Alaska, Hawaii, Puerto Rico, the US territories, and Canada across its six zones. Three classes of recipient still need attention:
  • Split states. A state spanning more than one time zone can’t be resolved by area code alone. Where a state’s assigned area codes straddle a boundary — Indiana (all America/Indiana/Indianapolis), Idaho (America/Boise), Michigan (America/Detroit), Kentucky and others — the map assigns the state’s area codes to the IANA zone that covers them rather than a generic “Eastern” or “Mountain” label. The IANA database then computes the offset correctly either way.
  • Year-round zones. Some recipients never change offset. Arizona’s area codes — 480, 520, 602, 623, 928 — resolve to America/Phoenix, which stays on UTC-7 all year. Hawaii’s 808 resolves to Pacific/Honolulu (UTC-10 all year). Saskatchewan’s 306, 474, and 639 resolve to America/Regina (UTC-6 all year). A “Mountain” or “Hawaii-Aleutian” label in your CRM is ambiguous; the resolved IANA name is not.
  • Toll-free and unassigned codes. Toll-free ranges (800, 833, 844, 855, 866, 877, 888) and codes NANPA hasn’t yet activated carry no geographic signal. The map deliberately excludes them, so a +1800 recipient falls through to step 5.
Worked examples — verify these against your own list before rollout: The full assignment the map mirrors lives in NANPA’s Active Codes report; US state calling windows consumes the same NANP inventory for the state overlays and quiet hours across DST works the Phoenix/Hawaii examples through the crossover dates.

​
The country-prefix map

Non-NANP numbers resolve by their E.164 country calling code to a representative zone, longest-prefix match first. The markets you most likely send to: For countries that span multiple time zones (Russia, Australia, Brazil), the map picks the most commercially significant zone — the conservative answer for a national list. When a specific contact’s zone differs (a Perth recipient on a +61 number resolving Australia/Sydney), override at step 1. The complete map covers Europe, the Middle East, Asia-Pacific, Africa, and Latin America — confirm any recipient’s resolved zone by previewing it (the response’s local_timezone tells you what won, step by step).

​
Fail-open or fail-closed: which policy value your posture needs

The unknown_timezone_policy is one of three values, and it is a tenant-owned control you set on your org: Pick the value by answering four questions: The one fail-closed-by-default case. The controls above are yours to tune. The sole exception is the TCPA federal voice dial window for US recipients: campaign and dialer voice to a +1 recipient that resolves no timezone is blocked regardless of your policy, with no tenant-side opt-out — that federal wire is the only guard the platform owns outright. Every other channel, and ad-hoc voice to non-US recipients, follows your configured policy (defaulting to fail-open skip). The quiet-hours preview enumerates the full reason set per channel — unknown_timezone_skip and unknown_timezone_deny are the two this policy produces.

​
Writing the org default timezone and the unresolved policy

Set unknown_timezone_policy in the dashboard under Settings → Voice, or in the quiet_hours block of organization settings over the API. The org default timezone feeds step 4 — mostly for email and push recipients that carry no phone number. The scoped pair that carries it is GET / PATCH /api/v1/settings/compliance/quiet-hours, worked through on the quiet hours configuration page.
Whole-document replace. A PATCH writes the quiet_hours block as-is: channel entries and org-level keys you don’t repeat disappear, and quiet_hours: null clears the whole block. To adjust one key — including unknown_timezone_policy — first GET, fold the change into the stored document, then PATCH the full document back.
Prefer the general settings merge surface instead? PUT /api/v1/settings/general also carries the same quiet_hours block (owner/admin) and merges at the top level — but it still replaces the quiet_hours key itself. Use whichever surface matches how you read settings; both feed the same gate.

​
Tenant ownership

Timezone resolution is entirely a tenant-side control: the override you pass per call, the org default timezone, and the unknown_timezone_policy value are all yours to set; the only guard the platform owns outright is the federal voice wire above. The day-one runbook that walks every tenant-owned gate in the order you configure it before the first send is Configure Your Tenant’s Posture Before the First Send — work that guide before rollout and this map stays the reference you come back to when a resolution surprised you.

​
Overriding per call: timezone_override

Preview calls accept a timezone_override parameter, and send paths accept a recipientTimezone hint. Both take an IANA name (America/Phoenix, not UTC-7) and win over every automatic source:
The response’s local_timezone field tells you which source won — echo it in your rollout checklist before launch and compare it against what your CRM expected. Field-by-field semantics for the whole response live on the quiet-hours preview page.

​
DST is a resolution problem, not a window problem

The window is always checked in recipient-local time, so the IANA zone is the thing to verify. Two recurring pitfalls, both resolved by getting the zone right:
  • Arizona and Hawaii never observe DST — a contact field stamped “Mountain” tells you nothing about Phoenix’s offset today. Resolve the zone and use it; the math follows the IANA database through whichever offset is current.
  • Crossover nights change UTC waits, not wall-clock windows — resolves to the same zone before and after. Recheck around each crossover by re-running the preview and confirming the zone name stays the expected IANA name.
Both pitfalls are worked through in quiet hours across DST — including the Arizona/Hawaii special cases, worked timelines for the 2026 March 8 / November 1 crossover dates, and the pre-launch preview procedure.

​
See also