User manual


Introduction

Convier is a REST API which allows users to exchange calendaring and scheduling information such as events, to-dos and journal entries directly in your users' calendars.. Generated requests comply with the iCalendar RFC 5545 standard and supports RFC 7986 and RFC 7953 extensions.

{primary} Integration packages to facilitate the integration of Convier API into your application are under development and should be available soon.

We recommend the use of Insomnia or Postman software to become familiar with the features of the API.

Authentication

The Convier API uses API tokens to authenticate requests. You can view and manage your API tokens in your Dashboard. Authentication to the API is performed via Bearer Auth using cURL headers:

-H 'Authorization: Bearer YOUR_TOKEN'

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Requests

All API requests use the base URL:

https://convier.me/api

Requests must be made using endpoints:

Component Endpoint Method
Event https://convier.me/api/event POST
To-do https://convier.me/api/todo POST
Journal https://convier.me/api/journal POST

Each request must be defined with the following parameters:

Parameter Key Definition Mandatory Type
Calendar calendar Global iCalendar information No array
Email email Email parameters No array
Download download Download generated request No bool
Component event, todo or journal Calendar component Yes array

The calendar attribute is furthermore described in the Calendar section of API reference.

{info} The download attribute allows to retrieve the text generated request in the API response. This feature is only available for the Enterprise subscription plan.

The email attribute allows to customize the email send to attendees. This attribute must be set as an array with children attributes:

Attribute Key Definition Mandatory Type
Localization locale URI that points to a document object No string
Body body URI that points to a document object to embed No string
Subject subject Format of the document object No string
Attach attach Send calendar request as attachment No string
Inline inline Insert calendar request inside email No string

{info} Customize email feature is only available for the Startup and the Enterprise subscription plan.

The following example shows how to create an event request with customized email content:

curl https://convier.me/api/event \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-d 'event[start][date]=04/26/2019 09:00 PM' \
-d 'event[end][date]=04/26/2019 11:00 PM' \
-d 'event[organizer][name]=Tony Stark' \
-d 'event[organizer][email]=ironman@avengers.com' \
-d 'event[summary][value]=Endgame premiere' \
-d 'event[description][value]=Bring the popcorn.' \
-d 'email[subject]=Yo!' \
-d 'email[body]=This the premiere of Endgame movie. Bring the popcon.' \
-d 'event[attendees][0][email]=USER_EMAIL'

The calendar components are described in the API reference. See Event, To-do and Journal for full documentation of these components.

Responses

The API returns JSON responses with attributes:

Attribute Key Definition Mandatory Type
Error error Error Yes bool
Message message Error description Yes string
UID uid Unique identifier of generated request Yes string
Data data Generated request data Yes string

{info} The uid attribute can be used to create update requests later.

{info} The data attribute contains the textual version of the generated calendar request. This feature is only available for the Enterprise subscription plan.

Errors

Convier uses conventional HTTP response codes to indicate the success or failure of an API request:

Code Definition
200 All good
400 Missing a required parameter
402 Parameters were present, but the request failed
500 Something went wrong on the server

Troubleshoot

Several users have reported that some email clients do not fully support the iCalendar format. We have summarised the compatibility information we currently have in the following table:

Clients Event Todo Journal
Outlook (Mac) Good Poor Poor
Outlook (Windows) Good Poor None
Thunderbird (Mac) Good Good None
Thunderbird (Windows) Good Good None
Gmail (Web) Good None None
Outlook.com (Web) Good None None

You may also encounter an error when retrieving (over an IMAP protocol) a request with the following message:

Retrieval failed using IMAP4 protocol for message.

This is usually due to Microsoft Exchange server trying to automatically process the request. This can be fixed using one of the solutions described below:

  • If you have access to the server, you should be able to disable this behavior by entering the following command in a terminal:
    Set-MailboxCalendarSettings -Identity "Username" -AutomateProcessing None
  • If you do not have access to the server:
    • Check that you have set the calendar method attribute to request. Other values seem to generate an error.
    • Try to set email attach to true and email inline to false. Generated requests will be sent as an attachment, which should be processed automatically by the client (see Table above) or manually by the user.

For any other errors not listed here, a community support is available.

{info} Dedicated support is available for the Startup and the Enterprise subscription plan.