Timestamp Conditions

When you created your Customer.io account, you likely saw a default segment called “Signed up” that uses the rule created_at is a timestamp.

image.png
image.png
is_a_timestamp_after_x_days_from_now.png
is_a_timestamp_after_x_days_from_now.png

When you build your own segment, we have a variety of timestamp-based rules:

Segmentation timestamp rules
Segmentation timestamp rules

This document will give some guidelines for how and when to use each.

What does “is a timestamp” even mean?

is a timestamp tells Customer.io to match users to your segment at the date and time represented by the timestamp value that is stored for the attribute you choose. is a timestamp will only evaluate to true once the date and time represented by the timestamp has come to pass. Timestamp-based rules are best used when you want to send a message on a certain date or X days after a certain date (by using delays).

Example

If created_at is 1461859200 (April 28, 2016, 4:00:00 pm), the user will match the segment April 28, 2016 at 4:00:00 pm.

Why are all signed-up users in this segment?

A user who enters a segment using only the rule created_at is a timestamp rule will never exit, so the segment itself contains all the users who matched in the past. This just checks that the value is a timestamp.

Example

I want my campaign to send messages to all users 7 days after they sign up, as long as they’re under 25 and they like pop music. Here’s how that might work:

  • Trigger segment: created_at is a timestamp
  • Filter segments: segment with the rule age is less than 25 AND segment with the rule favorite_music_type is equal to pop
  • Delay: 7 days
  • Messages

How this works

When users sign up, they are added to the campaign and the clock starts ticking. Once the delay passes, people are checked against the filter criteria (Is the user age under 25? Is pop their favorite music type?). If the filters match, the users belong to those two segments 7 days after signing up, and the message goes out. If not, the users skip the message or leave the campaign.

Why not just add all the rules in one segment?

Each rule inside a segment has a particular matching time and the overall matching time of the segment is dictated by the last rule matching. If we’d made the above example a trigger segment:

created_at is a timestamp

AND

age is less than 25

AND

favorite_music is equal to pop

The user would enter the segment when the last rule of the segment matches. If the users adds their age and their favorite music at the time the account is created all at once, then this might work. However, if someone signs up, but then takes seven days to add their age and/or music type, that’s when the delay will begin. In that case, a user might receive the message(s) weeks or months after they sign up, depending on when the other attributes are added.

Other timestamp rules and their interpretations

Using relative dates:

1. is a timestamp after X days from now

is a timestamp after a relative date of X days from now matches users whose date is at least X days in the future.

is a timestamp after X days from now
is a timestamp after X days from now

For example, a segment using the rule delivery_date is a timestamp after a relative date of 3 days from now. If we assume that “now” is March 1st, 2016, this segment will match users whose delivery_date is a timestamp corresponding to three days after March 1st. As soon as it’s less than three days from “now”, they will exit.

2. is a timestamp after X days ago

is a timestamp after a relative date of X days ago will match users whose date is within the past X days. This type of segment can be helpful if you want to create a newsletter and only send it to users who signed up in the past 7 days to let them know about a special promotion or warn them about a bug.

is_a_timestamp_before_x_days_ago.png
is_a_timestamp_before_x_days_ago.png

For example, the segment created_at is a timestamp after a relative date of 7 days ago will include users whose accounts are less than 7 days old. If today is October 8, 2016, the segment will match users who created their account from October 1, 2016 until now. They will exit the segment as soon as more than seven days passes.

3. is a timestamp before X days from now

is a timestamp before a relative date of X days from now matches users X days before this date. This type of segment is often used for billing-related campaigns.

is_a_timestamp_before_x_days_from_now.png
is_a_timestamp_before_x_days_from_now.png

For example, If you want to send a payment reminder 7 days before next_payment_date you’ll want to use the following trigger segment rule:

next_payment_date is a timestamp before a relative date of 7 days from now

Users will receive your message exactly 7 days before their next_payment_date and if you want to add multiple reminders, you just need to add a couple more messages to your workflow:

  • Message 1: No delay (sends 7 days before next_payment_date)
  • Message 2: 4 days (sends 3 days before next_payment_date)
  • Message 3: 7 days (sends on next_payment_date)

Users will never exit segments of this type, so if you want to automatically send payment reminders every month, you’ll need to constantly update the value of the next_payment_date attribute and reach out to our support team to change the campaign settings, so that users can enter it more than once.

4. is a timestamp before X days ago

This type of segment can be used if you want to send messages to older users.

is a timestamp before a relative date of X days ago matches users whose date is more than X days in the past

is_a_timestamp_before_x_days_ago.png
is_a_timestamp_before_x_days_ago.png

For example, if “now” is April 28, 2016 and we set up a segment with the rule join_date is a timestamp before 8 days ago, users with a join_date before April 20, 2016 will match.

Using specific dates:

1. is a timestamp before X date

is a timestamp before a specific date of X will match users whose date is before X. This condition can be used if you want to send messages to users for whom an attribute is a timestamp before a date.

For example, say we want to send a message to people who signed up for our app before December 1st. This is how we would do that:

is_a_timestamp_before_x_date.png
is_a_timestamp_before_x_date.png

This segment includes all the users who signed up before the timestamp 1575158400: December 1st, 2019, 12:00:00 GMT.

2. is a timestamp after X date

is a timestamp after a specific date of X will match users whose date is after X. This condition can be used if you want to send messages to users for whom an attribute is a timestamp after a date.

For example, say we want to send a message to people who signed up for our app after December 1st. This is how we would do that:

is_a_timestamp_after_x_date.png
is_a_timestamp_after_x_date.png

This segment includes all the users who signed up after the timestamp 1575158400: December 1st, 2019, 12:00:00 GMT.

3. is a timestamp between X date and Y date

is a timestamp between X and Y will match users whose date is between X and Y. This condition can be used if you want to send messages to users for whom an attribute is a timestamp between two dates.

For example, say we want to send a message to people who signed up for our app in December. This is how we would do that:

is_a_timestamp_between_x_date_and_y_date.png
is_a_timestamp_between_x_date_and_y_date.png

This segment includes all the users who signed up between the timestamps 1575158400 and 1577750400: December 1st, 2019, 12:00:00 GMT and December 31st, 2019, 12:00:00 GMT, inclusive.

Best Practices

If you want to take full advantage of timestamp rules, they are best used as unique rules inside a trigger segment, so that the users can match the time condition, and have delays calculated from that moment onwards.

If you have specific questions regarding how timestamps work, have a look at our FAQ.