This is How Email Calendar Event Invites Work

Ever curious how calendly, cal.com, and Meetup send you an email that integrates seamlessly with your email? Wonder no more! I break it down for you in this article.

This all started when I began developing my Ink-In-Time project. I’ve never been a fan of calendly’s privacy policy. The only other option (cal.com) was way over-engineered for my needs. I just needed a simple scheduling app that could find blocks of time and send out an invite.

Because of this, I knew I needed to find out how calendars integrate into email systems. I use ProtonMail that uses the feature, but other major email providers like Gmail and Outlook do the same thing.

Photo by Towfiqu barbhuiya on Unsplash

High Level View

At a 30,000-foot level view, a .ics file is generated, and sent as an attachment to your email. Within the ICS are other event members, such as the organizer. This becomes important later.

This attachment is detected by your email client. If you have a calendar associated with the email (as found by Gmail, Thunderbird, ProtonMail, etc) then you’re prompted to add it as an event.

At the same time, an email is sent to the other participants verifying that you accepted/declined the event.

So as you can see it’s completely serverless and nondistributed. The only action taken is sending emails back and forth.

The Email Attachment

This is the meat 🥩 and potatoes 🥔 of the system (or tofu and kale if you prefer). You can even investigate it yourself. Open up an email for a recent event invitation and check out the contents. Here’s an example of mine (sorry, cyber criminals, I removed anything sensitive):

As you can see an ICS is nothing special. Just a text file. Yes, to the untrained eye it can look very overwhelming. But don’t shut your laptop screen just yet! I’ll walk through it.

BEGIN:VCALENDAR
...
ENV:VCALENDAR

This is the wrapping context to show it’s a vcalendar . There are other vcard schemas as well, but this is a vcalendar .

PRODID:-//Custom//Scheduler//EN

This line is (mostly) arbitrary. Just helps the system determine the source of the scheduler. For example, the one I set for Ink-In-Time is PRODID:-//Ink-In Time//Damn Good Technology 1.0//EN .

VERSION and METHOD are pretty self-evident and will remain the same.

BEGIN:VEVENT
...
END:VEVENT

This begins and ends the VEVENT context. You can have multiple VEVENT contexts per VCALENDAR . This is how you can export/import an entire calendar between systems.

UID:b8755c7c-6cd9-11ed-8f34-b5cf5394dae1

This is a unique ID for the event, and the main way a serverless, email-only system determines the event. This is generated on a per-event basis by the event scheduler (Ink-In-Time does this here: https://github.com/src-r-r/ink-in-time/blob/main/src/email.py#L78).

STATUS:CONFIRMED

No ambiguity here. When you click YES to an email invitation this attachment is modified to include the status “Confirmed.” However, for the event organizer, the status is always confirmed, because (obviously) you wouldn’t be creating the event if you couldn’t attend.

ORGANIZER:organizeremail@example.com

This is the organizer’s email. Any response (“Yes,” “No,” “Tentative”) is sent to that email.

DTSTART:20221123T080000Z
DTEND:20221123T083000Z

The start and end time of the event. Z is the start of a timezone, if given.

SUMMARY:John Doe and Jane Smith
DESCRIPTION:This is a description of an example meeting\n 
There are even multiple lines

Summary and description.

END:VEVENT
END:VCALENDAR

Remember BEGIN:VEVENT and BEGIN:VCALENDAR at the beginning? You’d better, because other wise your ical won’t be valid. You can think of this as </body></html> in an HTML file. It’s just that the ICS authors are allergic to XML apparently.

The Email Exchange

This ICS file is all well and good, but it’s just sitting on the server not doing anybody any good. How does it get out to the other participants?

Well, Ink-In-Time is set up to use the Pythons smtp library. Other systems are different. Some may use MailGun or MailChimp. But what’s important is that the event is added as an attachment called calendar.ics and (most important) is attached as the filetype text/calendar .

Most email systems use this standard to detect an event invitation. Otherwise, it’s just a boring old email attachment muddled in with pictures of your cousin’s grandkids and rar files sent from strange email addresses.

Basically, there’s nothing too special about the ics file attached. The author of the ics file doesn’t have to do any special JavaScript coding to ensure the email application picks it up. Usually it’s up to the email application and the calendar application to work in harmony to make this happen.

There you Have It!

Mystery solved! Now you know how systems like Calendly and (the better alternative) Ink-In-Time work.

Now you have the know-how to build your own!

📆 If you’d like help setting up Ink-In-Time, or you need help with your tech stack, connect with me at https://damngood.tech. I provide a free 1 hour consultation and can provide solutions for your business needs.

❤️❤️❤️ I’d REALLY appreciate your support! If you like my articles consider becoming a subscribe at Kofi: https://ko-fi.com/damngood. Get articles 3 days early and get shout-outs on social media! ❤️❤️❤️