Introducing Agical.io, the smarter ICS file generator

Sanford Whiteman -

If you've used Marketo's dynamic ICS files (the "Calendar File" token type) you're probably not completely happy with 'em. While undeniably useful, they lack certain key elements we're used to when sending invites and requests via Outlook or other apps.

Major complaints from Marketo users:

  • no event reminders (alarms)
  • no all-day events
  • can't tokenize the event title

Reminders and all-days are part of the venerable ICS/iCalendar standard from 1998, and it's frustrating to have them missing from a modern product.

So about a year ago, I wrote a tiny web service that fills in all these gaps. I dubbed it MagICS (a purposely old-fashioned name) and chatted it up on the Marketo Community but no one seemed too taken with it. Changed to the slicker name Agical but still couldn't get users to pay attention to how cool it is/was! But finally, Marketo master Nicholas M. tried it out this week and gave me the feedback I needed: "it just works."

So, after a year, I've decided to publish it here.

Agical is incredibly simple to use. You just put a link in your Marketo email with appropriate query params, including dynamic {{lead.tokens}} or {{my.tokens}} in the link as needed. When a lead clicks the link, Agical generates a dynamic ICS file. It's just like the Marketo feature, only you can pass more event settings to Agical and thus get more event settings back out.

How do I use it?

The base URL is https://ics.agical.io/. To that URL, you add the following params (param names are case-sensitive):

subject — subject of the event (in ICS terminology, the "summary")

description — long description of event

organizer — person organizing event

location — location of event

attach — a URL that is related to the event, such as a webinar URL

Note: attach is one component I'm curious about support for across calendar platforms. It's harmless to include it in the ICS, and it's so helpful when it's supported (because you don't have to hunt in the description or location for a URL). So please let me know what you find with it.

dtstart — start date/time in ISO date format

dtend — end date/time in ISO

ISO dates are formatted like so:

2016-05-26T15:00:00-04:00 (with static time offset); or
2016-05-26T15:00:00Z (in UTC, a.k.a. Zulu time)

Agical will always translate to UTC in the final ICS file.

duration — as an alternative to dtend specify a duration like 1H or 30M

reminder — the alarm time, in minutes, before the event

allday — use allday=1 for an all-day event, omit for a standard event

recur — set to recur=weekly or recur=monthly for recurring events, or omit for a one-time event

recuruntil — set to the end date/time of a recurring event

echo — optional parameter to print the contents of the resulting ICS to your browser instead of downloading it. This is very, very useful for debugging.

uid — optional parameter to hard-code the unique identifier for the event, allowing (in some calendar apps) the ability to update the event over time. The string @ics.agical.io is automatically appended to the value.

Here's an example URL (sorry for the wrapping, it's bound to happen):

https://ics.agical.io/?subject=Meet%20{{company.Account Owner First Name}}&organizer=Sandy&reminder=45&location=Sandy%27s%20Desk&dtstart=2016-10-26T15:00:00-04:00&dtend=2016-10-26T16:00:00-04:00&attach=http://www.example.com/

Does it work in all calendar apps?

You'll probably find that some parameters are ignored, or set to defaults, by some apps.

Google Calendar typically doesn't use the reminder time in the ICS file, instead using the lead's default reminder time. (For example, it'll set an alarm for 30m before instead of 45m before.) Better than no reminder at all! Yet sometimes Gcal does accept the "T-minus" time exactly as-is. Haven't been able to put my finger on what's different in those cases.

Outlook 2013, and maybe earlier, has the quirk that it wants to ignore the attach param, but won't ignore it — and will show a small warning — if it doesn't end with a slash. So attach=http://www.example.com/webinar/ is fine while attach=http://www.example.com/webinar is considered wrong, though neither will show in Outlook. Go figure. So you should include the trailing slash to be safe, if you're including attach at all.

In general, Agical uses only standard RFC 2445 features, so it will generate backward-compatible ICS files (since the standard is so old, there really aren't "modern" versions; it's more like modern software never bothered to implement old stuff).

I look forward to getting feedback about which params are respected by which apps. The goal of Agical is to present a standards-compliant, gracefully-degrading ICS file with advanced features made as... possible... as possible!

Any other gotchas?

Remember that you're building a URL. Which means (h/t Nicholas again) you need to encode reserved characters, just as you would with any other URL in an email. If you want to do a positive offset from UTC, that's 12:34:56%2B04:00, not 12:34:56+04:00 (literal plus signs have special meaning).

What's it cost?

Agical.io is free to use. It's hosted on Viaduct.io's FortRabbit's enterprise platform for 24/7 availability.

Current Agical.io service status

Update 2016-08-09: Add to Google Calendar support added

Agical can now create Add to Google Calendar links too!

Update 2016-09-01: Status chart added

Added Monitis widget.

Update 2017-06-12: Viaduct to FortRabbit

Noted hosting platform change.

Update 2018-08-28: Event duration support added

Agical now supports the duration parameter for ICS files (not supported by GCal).