Sign in Subscribe
Key Concepts

How Setting Relative Dates Works in Mautic

How Setting Relative Dates Works in Mautic

Understanding and using relative dates in Mautic can be intimidating in the beginning. It quickly becomes confusing how a certain relative date resolves to a specific date.

Do you think you already mastered it?

What specific date will first sunday of august +3 days 12:00 next year result in? I bet it isn't what you thought.

You'll know after this guide.

In this comprehensive guide I'll illustrate you the basic relative date functionality as well as some edge cases you habe to be aware of.

Foundation

Mautic allows you to use relative dates. What are relative dates?

Relative dates are expressed as some form of natural language text. E.g. +5 days 6 hours 30 minutes or 3 months ago or next saturday or last day of december. To be of use relative dates need an anchoring date.

💡
Relative dates use an anchoring date and add or subtract a specific amount of time to/from it. An anchoring date can be an event in Mautic (e.g. the date a user last clicked on a link) or a contact's custom field (e.g. the date of a purchase) that you set.

Example: This is useful to send someone a message if they visited a page 5 days ago.

Under the hood Mautic uses PHP's relative date function. PHP's documentation is more concise but lacks examples.

To get a good understanding what relative dates can do for you, it's important to define some abstract terms. It makes describing the relative date functionality easier. Stick with me, please:

  1. datenames: This refers to the days of the week. In Mautic, you can use the full day name or its abbreviated form (e.g., mon or monday for Monday, tue for Tuesday, etc.). Same goes for months: jan for January or October for October. It doesn't matter if you're using a capital first letter.
  2. reldate: This refers to specific words meaning a relative date or time: yesterday, today, tomorrow, midnight, noon. Except noon all of these set the time to midnight. So, yesterday actually means yesterday at 00:00. You can add a time: yesterday 08:00 to define a specific time of yesterday.
  3. number: A positive or negative number. Always prefix it with the plus or minus sign. E.g. +5 or -3.
  4. ordinal: You can use ranks such as first, second, third, and so forth to describe the x-th of something.
  5. reltext: The relative words next, last or previous. There is also ago, which negates the relative date that precedes it. This can be tricky (see below)!
  6. unit: This can be any time unit, such as ms or millisecond(s), sec or second(s), min or minute(s), hour, day, month, year, or plural forms like days, months, years. There is only the plural weeks and no week. You could even use weekdays.

Now, with these terms we can describe the grammar of Mautic's/PHP's relative dates.

💡
Relative statements are always processed after non-relative statements. This means that +1 week July 2008and July 2008 +1 week are equivalent.

Let's start with simple examples and work our way up:

Modifying The Date With a Number

This is probably the main use case for relative dates in Mautic. For this we use a number along with a unit. I'll use days, but you could as easily use week, month, etc.

Let's say our anchoring date is: Friday 28th of July 2023 14:23.

  • The relative date +5 days equals to: Wednesday 2nd of August 2023 14:23. It re-uses the exact time of days.
  • The relative date +5 days 12:00 equals to: Wednesday 2nd of August 2023 12:00. It sets the time of day to the specified time.
  • The relative date +3 days +1hour equals to: Monday 31st of July 2023 15:23. It modifies the time of day ad adds one hour.
  • The relative date -5 days equals to: Sunday 23rd of July 2023 14:23.
  • The relative date -5 days 12:00 equals to: Sunday 23rd of July 2023 12:00.
  • The relative date -3 days +1hour equals to: Tuesday 25th of July 2023 15:23.
  • The relative date 5 days ago equals to: Sunday 23rd of July 2023 14:23.
⚠️
You can't use decimal numbers! +1.5 days won't equal to +1 day 12 hours. Mautic/PHP will parse it as +1 5 days.
Anchoring date is: Friday 28th of July 2023 15:18.
· +1 days equals to: Saturday 29th of July 2023 15:18.
· +1.5 days equals to: Wednesday 2nd of August 2023 15:18.

Using ago

ago can be a bit tricky. ago negates the relative date, which comes before it. If you're using something like +1 hour this can easily become a confusing situation. See for yourself:

Let's say our anchoring date is: Friday 28th of July 2023 14:23.

  • The relative date 5 days ago 12:00 equals to: Sunday 23rd of July 2023 12:00. It's the same as -5 days 12:00.
  • The relative date 3 days ago +1 hour equals to: Tuesday 25th of July 2023 15:23. It's the same as -3 days +1 hour.
  • Now the “problem”: The relative date 3 days +1 hour ago equals to: Tuesday 25th of July 2023 13:23. It's the same as -3 days -1 hour.
💡
My tip here is: Don't use ago as it could easily mess things up. An example? Say you want to follow up a sale a month minus 5 days after it happened. You might write: +1 month 5 days ago. But this results in 1 month and five days ago! Your follow-up will never happen.

Using Specific Relative Dates datenames

By using specific relative dates I mean something like Friday or next Tuesday or first Monday of next month. You can use all sorts of combinations of datenames, reldate, ordinal or reltext.

💡
Using a name for one of the weekday datenames or reldate sets the time of day always to midnight. Add a specific time of day if you need it.

If we're using a weekday around the current day, which day is actually used? Let's see:

Anchoring date is: Friday 28th of July 2023 14:23.

  • Friday equals to: Friday 28th of July 2023 00:00. (Today).
  • this Friday equals to: Friday 28th of July 2023 00:00. (Today).
  • next Friday equals to: Friday 4th of August 2023 00:00. (Next week).
  • last Friday equals to: Friday 21st of July 2023 00:00. (Last week).
  • previous Friday equals to: Friday 21st of July 2023 00:00. (Last week).
  • Thursday equals to: Thursday 3rd of August 2023 00:00. (Next week).
  • this Thursday equals to: Thursday 3rd of August 2023 00:00. (Next week).
  • next Thursday equals to: Thursday 3rd of August 2023 00:00. (Next week).
  • last Thursday equals to: Thursday 27th of July 2023 00:00. (This week).
  • previous Thursday equals to: Thursday 27th of July 2023 00:00. (This week).
  • Saturday equals to: Saturday 29th of July 2023 00:00. (This week).
  • this saturday equals to: Saturday 29th of July 2023 00:00. (This week).
  • next Saturday equals to: Saturday 29th of July 2023 00:00. (This week).
  • sat +1 week equals to: Saturday 5th of August 2023 00:00.
  • last Saturday equals to: Saturday 22nd of July 2023 00:00. (Last week).
  • previous Saturday equals to: Saturday 22nd of July 2023 00:00. (Last week).
💡
If the relative week day (Friday in this case) matches the current day, Mautic will use the current day. If not, Mautic will always use the next upcoming weekday without an additional modifier.

As a result you can't skip a week. If we're having Friday next sat can't match the Saturday of next week. You'd have to use sat +1 week.

Also, I would refrain from using this PHP simply ignores it. So, if we're having Friday this thursday it technically equals just writing thursday. As a result, Mautic won't target this week's Thursday (i.e. yesterday), but the upcoming Thursday of next week.

As I say'd the datenames and reldate overrides the time of day. Add a specific time if you need it:

Anchoring date is: Friday 28th of July 2023 14:43.

  • yesterday equals to: Thursday 27th of July 2023 00:00.
  • tomorrow equals to: Saturday 29th of July 2023 00:00.
  • yesterday 12:00 equals to: Thursday 27th of July 2023 12:00.
  • tomorrow 06:45 equals to: Saturday 29th of July 2023 06:45.

Anchoring date is: Friday 28th of July 2023 14:43.

  • Thursday 08:15 equals to: Thursday 3rd of August 2023 08:15.
  • Saturday 08:15 equals to: Saturday 29th of July 2023 08:15.
  • next Monday 08:15 equals to: Monday 31st of July 2023 08:15.

Using an Ordinal Day

Now we're using ordinal to target some specific days. We can specify an arbitrary x-th of something (day, month, etc.).

Anchoring date is: Friday 28th of July 2023 14:43.

  • first sat of August equals to: Saturday 5th of August 2023 00:00.
  • last sunday of December equals to: Sunday 31st of December 2023 00:00.
  • last day of next month equals to: Thursday 31st of August 2023 14:43.
  • last day of next month equals to: Thursday 31st of August 2023 14:43.
💡
Notice how using a weekday sets the time midnight and how using just day won't.

Relative Dates Aren't Always Obvious

Well, that have been a lot of dates and numbers, right?

There are many more combinations, and I can't dive into all of them. But if you understood how the above works, you build your own relative dates easily. A fairly wild example is this:

  • first sunday of august +3 days 12:00 next year

If the anchoring date is: Friday 28th of July 2023 14:13 then this relative date equals to:

  • Friday 9th of August 2024 12:00.

Why not Wednesday 7th of August?

  • first sunday of august results in Sunday 6th of August 2023.
  • +3 days adds three days to this date, giving us Wednesday 9th of August 2023.
  • next year adds a whole year, as in 365 days, on this date. That's why the date is Friday 9th of August 2024 12:00.

I hope you stuck with me, and it was worth it. There are some gotchas using relative dates, which could easily ruin your segments or campaigns in Mautic.

If you liked learning about this technical part of Mautic, then consider to

Happy marketing!

Read next

Comments ()