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.
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.
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 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 theEnterprise
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 theEnterprise
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.
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 theEnterprise
subscription plan.
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 |
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:
Set-MailboxCalendarSettings -Identity "Username" -AutomateProcessing None
method
attribute to request
. Other values seem to generate an error.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 theEnterprise
subscription plan.