Have you ever organized an event where many of the registered guests didn't attend the event? To ensure maximum turnaround in an event, an email with an AddToCalendar link can be beneficial as it will help to remind the attendees once they add it to their calendar.

Let's see how we can generate and add this magical link in our emails.

What you’ll need?

  1. An ICS (Internet Calendar Scheduling) File
  2. An MVC API to download the file

An ICS File 👀 What is that?

The ICS format is a universal calendar file format that all popular calendar applications, including Microsoft Outlook, Apple Calendar, Google Calendar, and Mozilla Thunderbird Lightning Calendar, create and recognize.


In more useful words, it is a plain text file that includes information about calendar events such as:

  1. Title
  2. Description
  3. Start and End time
  4. Location / Url
  5. Alert Trigger
  6. Organizer

Still, having doubts? Learn more about ICS here.

To give you an idea about ICS, let's assume you are organizing an event on Introduction to Next.js Framework. You want to make sure most of the guests check in to the event, so what should you do? First, create an ICS File that has the following information.

  1. Name: Introduction to Next.js
  2. Description: Next.js is a complete full-stack framework built on top of React.js. If you have little experience in react and looking forward to knowing more about the react.js ecosystem, you should also know about the Next.js framework.
  3. StartDate : 25 Sep 8:00 am , EndDate: 25 Sep, 9:00 am MDT
  4. HostName : Anjali Sharma
  5. HostEmail: anjali.sharma@kiprosh.com
  6. Weburl : https://us02web.zoom.us/j/84433742933

How to Generate ICS File?

Below is the ICS file which we will be generating. It includes the prerequisite to add the ICS file to the calendar and details about the event. Other sections such as time zone & triggers can also be added.

ICS File Content

The following code sample shows how to generate content of ICS file using C#

 public string GetFileContent(Guid evenId)
 {
     // This function will give us the eventInformation from Database
     var eventData = GetEventDetails(eventId);    
     
     // Get ICS version,prodId,calscale and method data
     var content= GetICSPrerequisiteData();

     // Set Event Information
     content.AppendLine("BEGIN:VEVENT");
     // Event time
     content.AppendLine($"DTSTART;TZID=America/Denver:{eventData.StartDate.ToString("yyyyMMddTHHmm00")}");
     content.AppendLine($"DTEND;TZID=America/Denver:{eventData.EndDate.ToString("yyyyMMddTHHmm00")}");   
     // Event host
     content.AppendLine($"ORGANIZER: CN = {eventData.HostName}: MAILTO: {eventData.HostEmail}");

     // Event Info
     content.AppendLine($"DESCRIPTION:{eventData.description}");
     content.AppendLine($"SUMMARY:{eventData.Name}");
     content.AppendLine($"URL:{eventData.WebUrl}");

     content.AppendLine("END:VEVENT");            
     content.AppendLine("END:VCALENDAR");
     
     return content;
}
Function to get ICS file content (C#)

How will this ICS File work?

To make this file work, we'll need an MVC API to generate the file for us. To know more about MVC APIs click here.

Let's say we identify the events with their IDs. Based on the IDs we generate the ICS file because we need different files for different events. The MVC API that does this for us will look something like this:

        
[HttpGet]
[Route("ics")]
public HttpResponseMessage GenerateICSFile([FromUri]Parameter<System.Guid> model)
{
    try{
         // Get file content for eventId passed in Url 
         var fileContent = GetFileContent(model.Value);
         
         var response = Request.CreateResponse();
         
         // Set ContentType                           
         response.Headers.Add("ContentType", "text/calendar");
         
         response.Content = new StringContent(fileContent, Encoding.UTF8, "text/calendar");
         // Response as a downloadable file
         response.Content.Headers.ContentDisposition = new System.Net.Http.Headers.ContentDispositionHeaderValue("attachment");
            
         // Set file name for file
         response.Content.Headers.ContentDisposition.FileName = $"invite.ics";
         return response;
      }
      catch (Exception ex)
      {
          return Request.CreateResponse(HttpStatusCode.InternalServerError, new { Error = ex.Message });
      }
}
API to download ics file (MVC API in C#)

How to connect an email to this API?

Add the API endpoint link that we created above along with the email and that's it!

// API link to download file
string AddToCalendarLink = "https://kiprosh.com/api/generatefile/ics?Value=3d6e6862-8ce5-4c9d-9e86-f7ac8ab3002a"

// Insert this Html link in email while parsing the template
<a href="AddToCalendarLink">Add to your calendar</a>

What happens when you click AddToCalendar link?

The ICS file will be downloaded. For Android users, it might look like this:

ICS file in Android

Things to watch out for:

1. Multiline Descriptions:

It's not always possible to have a single line of description. In case if you have a multiline description as shown below. You might come across the issue where the only first-line is visible.

Next.js is a complete full-stack framework built on top of React.js.
If you have little experience in react and looking forward to know more about react ecosystem then you should also know about Next.js framework.

It's because the ICS file does not identify the new line character and it considers it as the end of the description. To overcome that we can use the below code before adding a description.

event.Description.Replace("\n", "\\n").Replace("\r", "\\r");

2. iPhone and Outlook calendars:

iPhone and Outlook calendars unfortunately and unsurprisingly do not support alerts added in the ICS file. This can be fixed by editing the invite file and adding a trigger for a reminder.

Hope this article was helpful to you. Enjoy having more guests at your events!