Calendars

A calendar belongs to one connected mailbox: the mailbox’s own primary calendar, or another calendar the mailbox can open at the provider, such as a shared team calendar. Carom imports calendar events only from calendars with sync turned on. Use this resource to see which calendars Carom knows about and to turn syncing on or off.

When Carom first finds a mailbox’s calendars, it turns sync on for the primary calendar and for calendars the mailbox owns, and leaves it off for the rest. After that, the setting changes only when someone changes it. Your key sees the calendars of every mailbox your key’s user can read: mailboxes they own, mailboxes whose view_policy or send_policy is everyone, and mailboxes whose grants include them.

#The calendar object

Returned by both calendar endpoints, and embedded in each calendar event under calendars.

Attributes

  • idstring · uuid

    Unique identifier for the calendar.

  • namestring · nullable

    The calendar’s name at the provider. A primary calendar is often named after its email address.

  • descriptionstring · nullable
  • access_rolestring · nullable

    The mailbox’s level of access to the calendar at the provider. freeBusyReader occurs only on Google calendars.

    ownerwriterreaderfreeBusyReader
  • mailbox_idstring · uuid · nullable

    The mailbox the calendar belongs to.

  • sync_enabledboolean · nullable

    Whether Carom imports events from this calendar. Change it with Update a calendar.

  • primaryboolean · nullable

    True for the mailbox’s primary calendar.

The calendar object 
{
  "id": "eaa47c21-17fa-456b-a381-db96b0191f5b",
  "name": "dana@harborline.example",
  "description": null,
  "access_role": "owner",
  "mailbox_id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
  "sync_enabled": true,
  "primary": true
}
get/calendars Read key

#List calendars

Without mailbox_id, returns the calendars visible to your key that have sync turned on. With mailbox_id, returns every visible calendar of that mailbox, synced or not, which is how you find calendars to turn on. Returns every calendar in one response; the list isn’t paginated.

Query parameters

  • mailbox_idstring · uuid

    Only calendars of this mailbox, including those with sync turned off.

Returns

  • collectionobject
    Show 2 child attributesHide child attributes
    • recordsarray of calendars
    • total_resultsinteger

      The number of calendars in records.

Errors

  • 400invalid_requestmailbox_id is present but empty.
get/calendars 
curl "https://api.carom.io/calendars?mailbox_id=d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "collection": {
    "records": [
      {
        "id": "eaa47c21-17fa-456b-a381-db96b0191f5b",
        "name": "dana@harborline.example",
        "description": null,
        "access_role": "owner",
        "mailbox_id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
        "sync_enabled": true,
        "primary": true
      },
      {
        "id": "6515d415-9385-4723-b9b0-4906618a5c85",
        "name": "Harborline team events",
        "description": "Offsites, all-hands, and holidays",
        "access_role": "reader",
        "mailbox_id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
        "sync_enabled": false,
        "primary": false
      }
    ],
    "total_results": 2
  }
}
patch/calendars/{id} Write key

#Update a calendar

Turns syncing on or off for one calendar. Turning it on starts an import right away.

Only the owner of the calendar’s mailbox can change it. Other keys that can see the calendar, including an account admin’s, get 403 permission_denied.

Path parameters

  • idstring · uuidrequired

Request body application/json

  • calendarobjectrequired
    Show 1 child attributeHide child attributes
    • sync_enabledboolean

      true to import this calendar’s events, false to stop.

Returns

The updated calendar object, wrapped in calendar.

Errors

  • 400invalid_requestThe body has no calendar object, or sync_enabled isn’t a boolean.
  • 403permission_deniedThe calendar belongs to a mailbox your key’s user doesn’t own.
  • 404record_not_foundNo calendar with that id is visible to your key.
patch/calendars/{id} 
curl -X PATCH https://api.carom.io/calendars/6515d415-9385-4723-b9b0-4906618a5c85 \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "calendar": { "sync_enabled": true } }'
Response200 
{
  "calendar": {
    "id": "6515d415-9385-4723-b9b0-4906618a5c85",
    "name": "Harborline team events",
    "description": "Offsites, all-hands, and holidays",
    "access_role": "reader",
    "mailbox_id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
    "sync_enabled": true,
    "primary": false
  }
}