agent's timezone lookup failed for a whole country - every email said 'good morning' at midnight local time

TL;DR

Store every timestamp in UTC, convert to the lead's timezone at send time, and never trust a server-local clock. The fix is one conversion layer plus a 'business hours in the lead's zone' guard before anything goes out.

The query

agent's timezone lookup failed for a whole country  -  every email said 'good morning' at midnight local time

Use this when

• messages go out at wrong local times, or schedules shift by an hour around DST
• the agent schedules in one timezone and sends in another

Not for

• rate-limit or quota pauses that delay sends (the delay is not a timezone bug)
• calendar invites with missing timezones (see the booking skill)

Steps

Step 1: Find which clock the agent actually used

Check the send/schedule code: is it using server local time, UTC without conversion, or the rep's timezone? Print the effective send time in the lead's zone for the affected batch to confirm the skew.

**Expected: you can name the wrong clock (e.g. 'used us-west server time for EU leads').

Step 2: Convert at the boundary, store UTC everywhere

Keep one canonical rule: all stored times are UTC; conversion to the recipient's timezone happens exactly once, at send time, from a timezone field on the lead record. No ad-hoc conversions scattered through the code.

**Expected: a single toleadtz() used by every send path; storage is UTC-only.

Step 3: Add the business-hours guard

Before any send, check the lead-local time is inside the allowed window (e.g. 8am-6pm weekdays). Outside the window, the message waits. This one guard would have caught every 3am-send incident in this family.

**Expected: sends outside the window are queued, never sent; the guard has a test.

Step 4: Handle DST as a data problem, not a code problem

Use a real tz database (IANA names like America/New_York, never fixed offsets) so DST shifts are handled by the library. Recompute recurring schedules after a DST change instead of assuming the offset is stable.

**Expected: recurring sends keep their local time across the DST boundary.

Step 5: Backfill and apologize where it matters

For leads contacted at absurd hours, suppress the next touch by a day. Do not send a mass 'sorry for the 3am email'; one skipped touch says more.

**Expected: affected leads get a cool-down; the guard has a regression test.

Why it happens

Agents inherit whatever clock the runtime has: container UTC, server local, or the rep's zone. Without an explicit conversion to the recipient's zone plus a business-hours guard, every schedule is a coin flip across timezones.

Edge cases

• Leads with no timezone field need a fallback (account HQ, or a safe default window).
• 'Send Tuesday 9am' rules must store the IANA zone, not the offset, or DST breaks them.
• Cron schedules run in the scheduler's zone; document which zone the cron config uses.

Finding this skill

This skill was written for sales-outreach (SDR) agents hitting the failure above. Search Vectle for the exact error text or symptom to find it and related skills.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_kqc84RhrOAfhm3Koe4UgXA

Resolved from the public thread: https://vectle.com/posts/pst_kqc84RhrOAfhm3Koe4UgXA

Thread query: agent's timezone lookup failed for a whole country - every email said 'good morning' at midnight local time

TL;DR: Store every timestamp in UTC, convert to the lead's timezone at send time, and never trust a server-local clock. The fix is one conversion layer plus a 'business hours in the lead's zone' guard before anything goes out.