Email Countdown Timer

Overview

The Email Countdown Timer add-on lets you add animated countdown timers directly inside your Groundhogg emails. Timers are rendered as animated GIFs and work in virtually every email client without any JavaScript. You can create fixed deadlines for sale events, evergreen countdowns personalised to each contact, or flexible delay-based timers using natural language or merge tags.

You can download this add-on from the Groundhogg website or as part of a plan and install it on your website.

Adding a Countdown Timer to an Email

Open any email in the Groundhogg email editor. In the block inserter, find the Countdown block and drag it into your email wherever you want the timer to appear.

Timer Types

With the Countdown block selected, open the Block tab in the right panel to configure the timer. The first setting is Type, which controls how the deadline is calculated.

Fixed

The timer counts down to a specific date and time, the same for every contact who receives the email. Use this for real deadlines — a sale ending at midnight, a webinar starting at a set time, or an offer that expires on a particular date.

Select the date and time using the date and time picker that appears when Fixed is chosen.

Evergreen

Each contact gets their own personalised countdown window that starts from the moment their email was queued for sending. Every contact sees the same amount of time remaining — for example, 72 hours — regardless of when you sent the email. The countdown is anchored to the specific queue event for that contact, so it remains consistent every time they open the email.

Enter the number of days for the evergreen window when Evergreen is chosen.

Advanced

The Advanced type accepts a natural language date or delay string, giving you the most flexibility. Examples of valid inputs:

• August 15, 2026 — a specific future date
• +3 weeks — three weeks from when the email is sent
• tomorrow 5pm — the next day at 5pm
• {meta.trial_end_date} — a merge tag that resolves to a date from the contact’s record

Note: If you use a merge tag in the Advanced field, the timer preview in the email editor will not display the resolved date — it only becomes correct when the email is sent to a real contact. Use the Functional send mode when testing to verify the timer renders correctly.

Colour Options

Below the Type setting, four colour pickers let you customise the appearance of the timer to match your brand:

• Clock Font Color — the colour of the countdown numbers (days, hours, minutes, seconds)
• Label Color — the colour of the unit labels (DAYS, HOURS, MINUTES, SECONDS)
• Accent Color — the primary colour of the timer’s graphic elements and background shapes
• Background Color — the colour filling any transparent areas in the theme

Themes

The Email Countdown Timer includes 10 built-in visual themes. Select a theme from the Theme dropdown in the Block settings panel. Each theme has a different visual style and font — experiment with the colour pickers to see how each theme can be personalised.

How It Works

When Groundhogg sends an email containing a countdown timer, the timer image is embedded as an <img> tag pointing to your site. Each time the email is opened, the recipient’s email client loads the image fresh from your server, which generates and returns an animated GIF showing the current remaining time. Because the GIF is server-generated on every load, it always shows the correct remaining time up to the point the deadline passes.

GIF frames are cached on your server to keep generation fast. Cached frames that have not been accessed in 24 hours are automatically cleared.

The GIF contains up to 60 frames of animation (one per second), giving roughly one minute of smooth countdown animation before it loops. If the deadline has already passed when the email is opened, the timer displays zeros.

Creating a Custom Theme

You can register your own custom countdown timer themes using the groundhogg/email_countdown/themes filter. Custom themes require a PNG background image (recommended size 1200×300px) and a TTF font file.

The cleanest way to add a custom theme is to create a small WordPress plugin:

<?php
/*
Plugin Name: Custom Countdown Themes
Description: Adds a custom countdown theme for Groundhogg email timers.
Version: 1.0
Author: Your Name
*/

add_filter( 'groundhogg/email_countdown/themes', 'register_custom_countdown_themes' );

/**
 * Add one or more custom themes for the email countdown timer.
 *
 * @param array $themes
 *
 * @return array
 */
function register_custom_countdown_themes( array $themes ) {

    $themes['custom_theme'] = [
        'name'             => 'Custom Theme',
        'clock-size'       => 100,
        'clock-offset'     => 180,
        'clock-color'      => '#ffffff',
        'label-size'       => 22,
        'label-offset'     => 230,
        'label-color'      => '#ffffff',
        'accent-color'     => '#000000',
        'use-colon'        => false,
        'background-color' => '#ffffff',
        'days-format'      => '%d',
        'hours-format'     => '%H',
        'minutes-format'   => '%I',
        'seconds-format'   => '%S',
        'image'            => __DIR__ . '/custom-theme.png',
        'font'             => __DIR__ . '/custom-font.ttf',
    ];

    return $themes;
}

Place your custom-theme.png background image and custom-font.ttf font file in the same folder as the plugin file. Free fonts in TTF format are available from Google Fonts.

Once the plugin is activated, your custom theme will appear in the Theme dropdown in the email editor.

Developer Filters

groundhogg/email_countdown/themes

Filters the registered themes array. Use this to add, modify, or remove countdown timer themes. See the Custom Theme section above for a full example.

groundhogg/email_countdown/frame_limit

Filters the number of frames included in the generated GIF. The default is 60, giving approximately one minute of animation. Increase this to extend the animation window at the cost of higher server memory usage during generation.

add_filter( 'groundhogg/email_countdown/frame_limit', function( $limit ) {
    return 120; // 2 minutes of animation
} );

FAQs / Troubleshooting

Q. The timer is not showing in the email. What’s wrong?
A. The timer is delivered as an image loaded from your server. Some email clients block remote images by default. Recipients need to allow images in their email client for the timer to appear. This is the same behaviour as any other image in an email.

Q. The timer showed the wrong time when I sent a test email to myself.
A. When sending a test email, use the Functional send mode. The Preview send mode does not queue an event, so the Evergreen and Advanced timers cannot anchor correctly to a specific send time. Functional mode creates a real queue event, and the timer will render correctly.

Q. The timer still shows time remaining even though the deadline has passed.
A. Email clients cache images aggressively. If a recipient opened the email before the deadline and their email client cached the image, they may still see the old version. Most modern email clients will reload the image on subsequent opens, at which point the timer will show zeros.

Q. Can I use a countdown timer in a broadcast email?
A. Yes. Fixed and Advanced timers work the same in broadcasts. Evergreen timers also work in broadcasts — each contact’s countdown is anchored to the time their individual broadcast event was queued.

Q. My server is showing high memory usage when timers generate.
A. GIF generation uses the PHP GD library to render each frame in memory. If you are generating many timers simultaneously, you can reduce memory pressure by lowering the frame limit using the groundhogg/email_countdown/frame_limit filter. Frames are also cached, so repeated opens of the same timer reuse cached frames rather than regenerating them.