40

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.

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 will evaluate to true as soon as the value is a valid UNIX timestamp. However, when you use a segment with an is a timestamp condition to trigger a campaign, a person won’t begin the campaign until the timestamp’s date and time. This means a person can be a member of the segment, but not enter a campaign. This only applies to setting an attribute equal to is a timestamp, not relative conditions like is a timestamp before 3 days from now. 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 the segment condition is created_at is a timestamp, then someone will enter the segment when you set their created_at attribute to a timestamp, like 1917049881 (Tue Oct 01, 2030 01:51:21pm GMT+0000). This person would not start a campaign triggered by membership to this segment until Tue Oct 01, 2030 01:51:21pm GMT+0000, the date and time of their created_at attribute; though they will log a journey.

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.

Why are there 2 created at timestamps?

You might see two different timestamps when you try to pick out attributes: created_at and _created_in_customerio_at.

We maintain these two timestamps so you can differentiate between when you added a person to Customer.io, and when you first recorded a person outside of Customer.io.

• _created_in_customerio_at is the date-time when you added a person to Customer.io. We assign this value automatically, and it’s immutable.
• created_at represents the date-time when you first recognized a person—which might happen outside of Customer.io.

These values will be different if you create people records outside of Customer.io and then import people from a CRM, upload a CSV, use a database integration, etc.

These values will probably be the same if you add people directly to Customer.io, like when you use our JavaScript snippet, our SDKs, etc.

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.

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.

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.

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 want to make sure that you set your campaign’s Frequency setting lets people re-enter the campaign every month.

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

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:

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:

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:

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.