Skip to main content

How can we help you?

Search

How to Add Timezone Data to Your Directory

Before using Timezone Sending, you need to populate ContactMonkey with timezone data for your recipients. This article covers the two main methods: syncing from a data source or uploading a CSV.

These steps must be completed by an Owner or Administrator.

Choose Your Method

ContactMonkey supports two approaches for adding timezone data:

Method

Best For

Maintenance

Setup Difficulty
Data Source Sync (Recommended Organizations with Azure AD, Okta, HRIS, or similar systems Automatic Medium (requires IT collaboration)
CSV Upload Quick implementation or organizations wtihout data source integration Manual - requires periodic updates Low (can be done immmediately)

Method 1: Sync from Your Data Source (Recommended)

Direct integration with your data source ensures timezone data stays current automatically. When employees join, change locations, or update their information in your directory, the changes sync to ContactMonkey without manual intervention.

Supported Data Sources

  • Azure Active Directory (Azure AD)
  • Okta
  • HRIS systems (via API)
  • Other identity management platforms

Setup Process

Step 1: Work with Your IT Team

Collaborate with your IT team to identify:

  1. Which supported timezone data format is available in your organization? (Click here for options)
  2. Where does this timezone data reside?
  3. Can it be directly integrated with ContactMonkey?

Step 2: Contact ContactMonkey Support

Once you have answers to the above questions:

We'll guide you through the integration process specific to your data source.

Azure AD Setup Example

If you use Azure AD, you can store timezone information using custom extension attributes.

  1. Open https://admin.exchange.microsoft.com
  2. Under the sidebar's Recipients, click Mailboxes
  3. Double-click on any user from the list
  4. Click Others
  5. Click on Custom attributes
    • You will see up to 15 custom attribute input fields
    • This is the maximum number of allowed custom attributes per user
  6. Choose an input number (ex: 01) for users' timezone
  7. Enter an IANA timezone (ex: America/Toronto) into the chosen input field and click Save
    • Repeat this step for each user to set their timezone
    • Note: You must use the same input number for all users for consistency
  8. Follow the steps in this article to map ContactMonkey's Time Zone field to Azure's extensionAttribute01 (or extensionAttributeX where X is the input number you chose for timezones)

Once these steps are completed and your Azure AD sync is configured, imported contacts in ContactMonkey will automatically have their timezones assigned for optimal sending.

Method 2: CSV Upload

CSV upload is ideal for:

  • Quick implementation to start using Timezone Sending immediately
  • Organizations without direct data source integration
  • Testing Timezone Sending before committing to a full integration

⚠️ Important: CSV uploads require ongoing manual maintenance to keep timezone data accurate as your employee directory changes.

Setup Process

Step 1: Prepare Your CSV File

Create a CSV file with timezone data using one of the supported formats. Your CSV must include:

  • Required headers (see exact names here)
  • Timezone data in a supported format (IANA, GeoNames, Postal Code, or Country)

📥 Download a sample CSV template here

Step 2: Upload to ContactMonkey

  1. Click Directory at the top of your dashboard
  2. Click Sources
  3. Click Upload a CSV
  4. Select your desired file

Step 3: Select Fields to Import

During the import process:

  • Select only your new timezone fields under "Fields to be imported"
  • This updates existing records without creating duplicates
  • You do not need to create a new list during this import

⚠️ Important: You cannot upload timezone data CSV during the email scheduling process. CSV uploads with timezone data must be done in the Directory.

CSV Header Requirements

Headers must be exactly as listed below (case-sensitive):

  • Time Zone (for IANA format)
  • Postal Code
  • Country
  • geoname_id
  • country_name
  • country_code
  • city_name
  • subdivision_1_iso_code
  • subdivision_2_iso_code

The system will NOT recognize variations like Home Country, zipCode, or TimeZone.

Maintaining Your CSV Data

When using CSV uploads:

  • Update and re-upload your CSV whenever employee locations change
  • Remove employees who have left the organization
  • Add new employees with their timezone data
  • Review data accuracy regularly to ensure optimal email delivery timing

Preparing HRIS Data for Timezone Sending

Whether syncing or uploading via CSV, your HRIS data must use the exact header names and supported formats listed above.

Best Practices:

  1. Use IANA timezone format when possible (most accurate)
  2. Include country information with postal codes for better accuracy
  3. Ensure data consistency across all employee records
  4. Remove sensitive information before syncing/uploading

Verifying Your Setup

After adding timezone data:

  1. Navigate to Directory in ContactMonkey
  2. Select a few test contacts
  3. Verify their timezone information appears correctly
  4. Send a test email using Timezone Sending to confirm functionality

See Also

Related articles