How to convert UNIX timestamps to readable date formats using Jinja

This article explains how to convert UNIX timestamps stored in aggregates or customer attributes into readable date formats using Jinja filters.

By applying simple conversions, you can:

• Personalize communications with clear, user-friendly dates.

• Prevent exposing raw UNIX values in messages.

• Standardize date formats in templates for reporting and filtering.

Why does Bloomreach use UNIX timestamps?

UNIX timestamps offer a consistent, system-independent way to represent time. They record the number of seconds (or fractional seconds) since January 1, 1970 (UTC), making them useful for:

• Capturing and comparing event times.

• Tracking sessions and campaign interactions.

• Supporting analytics, event deduplication, and segmentation.

For example, Bloomreach stores timestamps for events like session_start, session_end, or first_session.

Why convert timestamps to readable formats?

1. Campaign personalization

When creating email or SMS campaigns, dynamic values like event times may be stored in UNIX format. Bloomreach does not automatically convert these into human-readable strings. If not converted manually, messages may include raw timestamps, which are unreadable to end users.

Example of a raw timestamp shown in a campaign:

Your last purchase was on 1477229914

Expected readable message:

Your last purchase was on 23/10/2016

2. Analytics & reporting

Readable dates make it easier to:

• Export and interpret reports.

• Review session logs.

• Share data with non-technical stakeholders.

Supported timestamp formats

Converting aggregates to readable dates

If you store an event’s timestamp in an aggregate, outputting it directly with Jinja:

{{ aggregates['aggregate_id'] }}

may return: 

1477229914

which is not human-readable.

Solution: Apply from_timestamp filter. 

{{ aggregates['aggregate_id'] | from_timestamp('%d/%m/%Y') }}

23/10/2016

Handling fractional second timestamps 

Some customer attributes may store timestamps with fractional seconds. Applying from_timestamp directly may fail.

This code: 

{{ customer.customer_attribute | from_timestamp('%d-%m-%Y') }}

may not work correctly.

Solution: Cast to an integer first.

{{ customer.customer_attribute | int | from_timestamp('%d-%m-%Y') }}

Output:

20-06-2025

Now your templates will show clear, readable dates instead of raw UNIX values.

Limitations

• Time zone handling:
  The from_timestamp filter defaults to UTC. If you need to localize time for specific regions, you must handle that separately (e.g., with additional logic or pre-processed attributes).

• Unsupported input formats:
  The filter only works with numeric UNIX timestamps. ISO-8601 strings or other custom formats cannot be converted directly and require preprocessing.

• Precision loss with fractional seconds:
  Casting to int removes sub-second precision. If milliseconds or microseconds are required, you may need alternative handling outside Jinja.
   

Best practices

• Use consistent date formats across campaigns (e.g., DD/MM/YYYY for EU audiences, MM/DD/YYYY for US).

• Always test with sample customer profiles to confirm correct formatting before sending campaigns.

• Where possible, normalize timestamps during data ingestion to simplify template logic.

• Document the date format used in each campaign or report for clarity and consistency.

By applying these practices, you ensure that campaigns display clear, localized, and user-friendly dates rather than raw UNIX timestamps.