SparkPost supports a wide range of different message types, from marketing and bulk mailings to transactional or trigger-based messages – even time-sensitive messages such as those used for two-factor authentication.  But how do you send a calendar invitation?  This is a question that several customers have recently asked me, so I thought that I would explore the ins and outs of how to successfully support calendar invitations through SparkPost.  

The trick is to send the invitation as an email message where the invitation is a specially formatted attachment, called an iCalendar file.  The following is a guide for how to send a calendar invite through SparkPost using the Transmissions API.  

The Scenario

Let’s imagine that when customers visit our website, we have a page inviting them to schedule a demo with our Sales team.  Upon clicking the “Schedule Demo” button, our system will automatically send a calendar invitation to the customer.  To accomplish this, I built a Python application that will accept the invitation details and recipient information, construct the calendar event, and send the invite to the attendee.

Steps

First, let’s lay out the primary steps for sending a calendar invite through SparkPost:

  1. Create calendar invitation as an iCalendar file
  2. Base64 encode the invitation
  3. Include the encoded invite as an attachment in the Transmissions API call
  4. Send the transmission to the invitees

Creating a Calendar Invitation

To create a calendar invitation, you will need to create an iCalendar file.  For this example, we are using the vCalendar format – a sample can be found on GitHub.  The iCalendar file is where we define the attributes of the meeting, such as the start and end time.  

I created the function “genCalInvite” and leveraged the “icalendar” package to construct an invitation from the sample using the event and recipient details that are passed into the script.  The function then outputs the constructed invitation.

One important thing to keep in mind is that it is important to ensure a unique UID is assigned for the event.  I generated a unique UID for the calendar event by leveraging the “uuid” package, which is then included in the iCalendar file.

Encoding the Invitation

Now that we have created the calendar invitation, the next step is to base64 encode it.  We need to base64 encode the iCalendar file because iCalendar is a binary encoded file format and SparkPost requires all such attachments to be carried as base64.  For this example, I used the “base64” package in Python to encode the invitation object.

Sending the Transmission

We are now ready to send the invite through SparkPost.  To do this, we will use the Transmissions API and include the base64 encoded invitation as an attachment.  It is important when including the attachment to indicate that the attachment type is “application/ics”, and that the file is stored with the “.ics” extension.  

In the Python script, I use the SparkPost Python library to send the email to the invitee.  Make sure to pass in your SparkPost API key!

Additionally, an example of the Transmissions API payload can be found in the GitHub project.

Message Received!

And now we’re done!  The message will be received by each of the recipients included in the Transmissions API with the calendar invitation that we sent.

Future Work

There are several different directions that this project could be taken.  One enhancement that I would like to make is supporting the ability to modify an existing calendar event.  Currently, the Python script will return the UUID of the calendar event that was sent to the recipients.  One idea that I have for accomplishing this is to store the unique UID of the event in a Postgres database along with the event details.  The Python script could then be modified to accept an existing UUID as an optional parameter along with the new event details, query the database to retrieve the existing event details, and send an updated invitation to all recipients.

Another enhancement that I would like to make is supporting the ability to invite multiple recipients at the same time.  One way to accomplish this might be to modify the recipient object to support a list of dictionaries and then update the invitation object accordingly.

I’d be interested to hear any suggestions or issues that you may have for future enhancements.

~ Darren