Multiple Recipients ALPHA
Required plan: EmergingAllows the creation of Smart Invites with multiple recipients.
As the behavior is very similar to the single recipient functionality it is recommended that you familiarize yourself with the exisiting Smart Invites documentation first.
The key difference is that rather than having a single recipient element or recipient_email parameter, there is instead a recipients collection.
Create or Update Invite #
Description #
Create a new Smart Invite for multiple recipients.
URL format #
{data_center_url}/v1/smart_invites
Example Request #
POST /v1/smart_invites HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}
Content-Type: application/json; charset=utf-8
{
"method": "request",
"recipients": [
{ "email": "cronofy@example.com" },
{ "email": "cronofy@example.org" }
],
"smart_invite_id": "your-unique-id-for-invite",
"callback_url": "https://yourapp.example.com/cronofy/smart_invite/notifications",
"event": {
"summary": "Board meeting",
"description": "Discuss plans for the next quarter.",
"start": "2024-12-31T09:30:00Z",
"end": "2024-12-31T10:00:00Z",
"tzid": "Europe/London",
"location": {
"description": "Board room"
}
},
"organizer": {
"name": "Smart invite application"
}
}Example Response #
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"recipients": [
{
"email": "cronofy@example.com",
"status": "pending"
},
{
"email": "cronofy@example.org",
"status": "pending"
}
],
"smart_invite_id": "your-unique-id-for-invite",
"callback_url": "https://yourapp.example.com/cronofy/smart_invite/notifications",
"event": {
"summary": "Board meeting",
"description": "Discuss plans for the next quarter.",
"start": {
"time": "2024-12-31T09:30:00Z",
"tzid": "Europe/London"
},
"end": {
"time": "2024-12-31T10:00:00Z",
"tzid": "Europe/London"
},
"location": {
"description": "Board room"
}
},
"attachments": {
"icalendar": "BEGIN:VCALENDAR\nVERSION:2.0..."
}
}Example callback #
Once a Smart Invite has been created for multiple recipients you will be able to receive notifications relating to it. These notifications will be sent as HTTP POST requests to the callback_url specified when the Smart Invite was created.
POST {CALLBACK_URL_PATH} HTTP/1.1
Host: {CALLBACK_URL_HOST}
Content-Type: application/json; charset=utf-8
Cronofy-HMAC-SHA256: {Base64(HmacSHA256(body_bytes, CLIENT_SECRET))}
{
"notification": {
"type": "smart_invite",
},
"smart_invite": {
"smart_invite_id": "example_id",
"callback_url": "http://www.example.com",
"recipients": [
{
"email": "example@example.com",
"status": "tentative",
"comment": "example comment",
"proposal": {
"start": {
"time": "2014-09-13T23:00:00+02:00",
"tzid": "Europe/Paris"
},
"end": {
"time": "2014-09-13T23:00:00+02:00",
"tzid": "Europe/Paris"
}
}
},
{
"email": "cronofy@example.org",
"status": "pending"
}
],
"reply": {
"email": "example@example.com",
"status": "tentative",
"comment": "example comment",
"proposal": {
"start": {
"time": "2014-09-13T23:00:00+02:00",
"tzid": "Europe/Paris"
},
"end": {
"time": "2014-09-13T23:00:00+02:00",
"tzid": "Europe/Paris"
}
}
}
}
}The key difference is that rather than having a single recipient element in the response, there is instead a recipients collection. The reply still relates to the specific response that triggered the notification.
Please note that for other recipients to receive the updated status of the replying participant, they must be sent a new ICS file for the event. This can be retrieved from the Invite Status endpoint.
Invite Status #
Description #
Retrieve the current state of a Smart Invite created for multiple recipients.
Example Request #
GET /v1/smart_invites?smart_invite_id=your-unique-id-for-invite&include_ics=true HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}Example Response #
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"recipients": [
{
"email": "example@example.com",
"status": "tentative",
"comment": "example comment",
"proposal": {
"start": {
"time": "2014-09-13T23:00:00+02:00",
"tzid": "Europe/Paris"
},
"end": {
"time": "2014-09-13T23:00:00+02:00",
"tzid": "Europe/Paris"
}
}
},
{
"email": "cronofy@example.org",
"status": "pending"
}
],
"smart_invite_id": "your-unique-id-for-invite",
"callback_url": "https://yourapp.example.com/cronofy/smart_invite/notifications",
"event": {
"summary": "Board meeting",
"description": "Discuss plans for the next quarter.",
"start": {
"time": "2024-12-31T09:30:00Z",
"tzid": "Europe/London"
},
"end": {
"time": "2024-12-31T10:00:00Z",
"tzid": "Europe/London"
},
"location": {
"description": "Board room"
}
},
"attachments": {
"icalendar": "BEGIN:VCALENDAR\nVERSION:2.0..."
}
}The difference to the request is that no recipient_email should be provided.
For the response, the difference is that rather than having a single recipient element and a replies collection in the response, there is instead a recipients collection.
Cancel Invite #
Description #
This method allows an invite to be cancelled, please note the returned ICS attachment must be sent to the recipients in order for the event to be removed from their calendar.
URL format #
{data_center_url}/v1/smart_invites
Example Request #
POST /v1/smart_invites HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}
Content-Type: application/json; charset=utf-8
{
"method": "cancel",
"recipients": [
{ "email": "cronofy@example.com" },
{ "email": "cronofy@example.org" }
],
"smart_invite_id": "your-unique-id-for-invite"
}Example Response #
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"recipients": [
{
"email": "example@example.com",
"status": "tentative",
"comment": "example comment",
"proposal": {
"start": {
"time": "2014-09-13T23:00:00+02:00",
"tzid": "Europe/Paris"
},
"end": {
"time": "2014-09-13T23:00:00+02:00",
"tzid": "Europe/Paris"
}
}
},
{
"email": "cronofy@example.org",
"status": "pending"
}
],
"smart_invite_id": "your-unique-id-for-invite",
"callback_url": "https://yourapp.example.com/cronofy/smart_invite/notifications",
"event": {
"summary": "Board meeting",
"description": "Discuss plans for the next quarter.",
"start": {
"time": "2024-12-31T09:30:00Z",
"tzid": "Europe/London"
},
"end": {
"time": "2024-12-31T10:00:00Z",
"tzid": "Europe/London"
},
"location": {
"description": "Board room"
}
},
"attachments": {
"icalendar": "BEGIN:VCALENDAR\nVERSION:2.0..."
}
}Remove Invite Recipient #
Description #
This method allows an individual recipient to be removed from an invite.
This results in two attachments, attachments.removed.icalendar that must be sent to the removed recipient to update them, and attachment.icalendar which may be sent to all active recipients to update the participant list.
URL format #
{data_center_url}/v1/smart_invites
Example Request #
POST /v1/smart_invites HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}
Content-Type: application/json; charset=utf-8
{
"method": "remove",
"recipient": { "email": "cronofy@example.org" },
"smart_invite_id": "your-unique-id-for-invite"
}Example Response #
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"recipients": [
{
"email": "example@example.com",
"status": "tentative",
"comment": "example comment",
"proposal": {
"start": {
"time": "2014-09-13T23:00:00+02:00",
"tzid": "Europe/Paris"
},
"end": {
"time": "2014-09-13T23:00:00+02:00",
"tzid": "Europe/Paris"
}
}
},
{
"email": "cronofy@example.org",
"status": "removed"
}
],
"smart_invite_id": "your-unique-id-for-invite",
"callback_url": "https://yourapp.example.com/cronofy/smart_invite/notifications",
"event": {
"summary": "Board meeting",
"description": "Discuss plans for the next quarter.",
"start": {
"time": "2024-12-31T09:30:00Z",
"tzid": "Europe/London"
},
"end": {
"time": "2024-12-31T10:00:00Z",
"tzid": "Europe/London"
},
"location": {
"description": "Board room"
}
},
"attachments": {
"icalendar": "BEGIN:VCALENDAR\nVERSION:2.0...",
"removed": {
"recipient": { "email": "cronofy@example.org" },
"icalendar": "BEGIN:VCALENDAR\nVERSION:2.0..."
}
}
}