Segmentation and Timestamp Rules

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.

Segments - Signed up segment

When you build your own segment, we have a variety of timestamp-based 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 the Customer.io to match users to your segment at the date and time value of the attribute you choose. 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

1. is a timestamp after X days from now

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

For example, a segment using the rule delivery_date is a timestamp after 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 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.

For example, the segment created_at is a timestamp after 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 X days from now matches users X days before this date. This type of segment is often used for billing-related campaigns.

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 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 X days ago matches users whose date is more than X days in the past

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.

5. is a timestamp between

If you want to send messages to users for whom an attribute is a timestamp between two values, you can do that with this condition.

is a timestamp between X and Y = match users whose date is between X and Y

Note: timestamps must be in seconds-since-epoch (January 1, 1970) format, also called unix time.

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:

December signups: "is a timestamp between"

This segment includes all the users who signed up between the timestamps 1512129600 and 1514721600: December 1st, 2017, 12:00:00 GMT and December 31st, 2017, 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.