Sign in

API reference / Calendar

Calendar

Events, invitations and answers.

Base URL https://api.zilomail.in

List events#

GET/v1/calendar/events
calendar.read

Events overlapping from–to (at most 92 days), repeats expanded: a repeating event appears once per occurrence, with the same id.

Query

fromstringrequired
ISO 8601 date and time, UTC, e.g. 2026-10-17T09:30:00.000Z.
tostringrequired
ISO 8601 date and time, UTC, e.g. 2026-10-17T09:30:00.000Z.

Answer · 200 OK

dataarray of object
idstring
titlestring
locationstring | null
descriptionstring | null
allDayboolean
startstring
ISO date and time; for all-day events, YYYY-MM-DD.
endstring
ISO date and time; for all-day events the last day, YYYY-MM-DD (inclusive).
recurringboolean
organizerobject | null
emailstring
namestring | null
mineboolean
The person organises it (they may change it; otherwise they answer).
guestsarray of object
emailstring
namestring | null
answerenum
One of NEEDS-ACTION, ACCEPTED, DECLINED, TENTATIVE.
myAnswerstring | null
updatedAtstring
ISO 8601 date and time, UTC, e.g. 2026-10-17T09:30:00.000Z.
curl "https://api.zilomail.in/v1/calendar/events?from=2026-10-01T00:00:00Z&to=2026-11-01T00:00:00Z" \
  -H "Authorization: Bearer $ZILO_TOKEN"
Answer · 200 OK
{
  "data": [
    {
      "id": "string",
      "title": "string",
      "location": "string",
      "description": "string",
      "allDay": false,
      "start": "2026-10-17",
      "end": "2026-10-17",
      "recurring": false,
      "organizer": {
        "email": "string",
        "name": "string"
      },
      "mine": false,
      "guests": [
        {
          "email": "string",
          "name": "string",
          "answer": "NEEDS-ACTION"
        }
      ],
      "myAnswer": "string",
      "updatedAt": "2026-10-17T09:30:00.000Z"
    }
  ]
}
Try it

Sign in to call it as yourself.

Get an event#

GET/v1/calendar/events/{id}
calendar.readETag · If-Match

Path

idstringrequired
An id this API gave out. Up to 64 characters.

Answer · 200 OK

idstring
titlestring
locationstring | null
descriptionstring | null
allDayboolean
startstring
ISO date and time; for all-day events, YYYY-MM-DD.
endstring
ISO date and time; for all-day events the last day, YYYY-MM-DD (inclusive).
recurringboolean
organizerobject | null
emailstring
namestring | null
mineboolean
The person organises it (they may change it; otherwise they answer).
guestsarray of object
emailstring
namestring | null
answerenum
One of NEEDS-ACTION, ACCEPTED, DECLINED, TENTATIVE.
myAnswerstring | null
updatedAtstring
ISO 8601 date and time, UTC, e.g. 2026-10-17T09:30:00.000Z.
curl "https://api.zilomail.in/v1/calendar/events/ID" \
  -H "Authorization: Bearer $ZILO_TOKEN"
Answer · 200 OK
{
  "id": "string",
  "title": "string",
  "location": "string",
  "description": "string",
  "allDay": false,
  "start": "2026-10-17",
  "end": "2026-10-17",
  "recurring": false,
  "organizer": {
    "email": "string",
    "name": "string"
  },
  "mine": false,
  "guests": [
    {
      "email": "string",
      "name": "string",
      "answer": "NEEDS-ACTION"
    }
  ],
  "myAnswer": "string",
  "updatedAt": "2026-10-17T09:30:00.000Z"
}
Try it

Sign in to call it as yourself.

Add an event#

POST/v1/calendar/events
calendar.writeIdempotency-Key

Phones syncing the calendar get it; guests get an invitation by email.

Body

titlestringrequired
Up to 300 characters.
locationstring
Up to 300 characters.
descriptionstring
Up to 5000 characters.
allDayboolean
Default false.
startstringrequired
ISO date and time (or YYYY-MM-DD for all-day).
endstringrequired
ISO date and time (or YYYY-MM-DD, the last day, for all-day).
guestsarray of string
Invited by email.
notifyGuestsboolean
Email invitations, updates and cancellations. Default true.
timeZonestring
For the times written in invitations, e.g. "Asia/Kolkata". Up to 64 characters.

Answer · 201 Created

idstring
titlestring
locationstring | null
descriptionstring | null
allDayboolean
startstring
ISO date and time; for all-day events, YYYY-MM-DD.
endstring
ISO date and time; for all-day events the last day, YYYY-MM-DD (inclusive).
recurringboolean
organizerobject | null
emailstring
namestring | null
mineboolean
The person organises it (they may change it; otherwise they answer).
guestsarray of object
emailstring
namestring | null
answerenum
One of NEEDS-ACTION, ACCEPTED, DECLINED, TENTATIVE.
myAnswerstring | null
updatedAtstring
ISO 8601 date and time, UTC, e.g. 2026-10-17T09:30:00.000Z.
curl -X POST "https://api.zilomail.in/v1/calendar/events" \
  -H "Authorization: Bearer $ZILO_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Review with Asha",
  "start": "2026-10-20T10:00:00+05:30",
  "end": "2026-10-20T10:30:00+05:30",
  "guests": [
    "asha@example.com"
  ],
  "timeZone": "Asia/Kolkata"
}'
Answer · 201 Created
{
  "id": "string",
  "title": "string",
  "location": "string",
  "description": "string",
  "allDay": false,
  "start": "2026-10-17",
  "end": "2026-10-17",
  "recurring": false,
  "organizer": {
    "email": "string",
    "name": "string"
  },
  "mine": false,
  "guests": [
    {
      "email": "string",
      "name": "string",
      "answer": "NEEDS-ACTION"
    }
  ],
  "myAnswer": "string",
  "updatedAt": "2026-10-17T09:30:00.000Z"
}
Try it

Sign in to call it as yourself.

Change an event#

PATCH/v1/calendar/events/{id}
calendar.writeETag · If-Match

Only the organiser can change an event; guests answer with answer.

Path

idstringrequired
An id this API gave out. Up to 64 characters.

Body

titlestring
Up to 300 characters.
locationstring
Up to 300 characters.
descriptionstring
Up to 5000 characters.
allDayboolean
Default false.
startstring
ISO date and time (or YYYY-MM-DD for all-day).
endstring
ISO date and time (or YYYY-MM-DD, the last day, for all-day).
guestsarray of string
Invited by email.
notifyGuestsboolean
Email invitations, updates and cancellations. Default true.
timeZonestring
For the times written in invitations, e.g. "Asia/Kolkata". Up to 64 characters.
answerenum
A guest's answer: the organiser gets it by email. One of ACCEPTED, TENTATIVE, DECLINED.

Answer · 200 OK

idstring
titlestring
locationstring | null
descriptionstring | null
allDayboolean
startstring
ISO date and time; for all-day events, YYYY-MM-DD.
endstring
ISO date and time; for all-day events the last day, YYYY-MM-DD (inclusive).
recurringboolean
organizerobject | null
emailstring
namestring | null
mineboolean
The person organises it (they may change it; otherwise they answer).
guestsarray of object
emailstring
namestring | null
answerenum
One of NEEDS-ACTION, ACCEPTED, DECLINED, TENTATIVE.
myAnswerstring | null
updatedAtstring
ISO 8601 date and time, UTC, e.g. 2026-10-17T09:30:00.000Z.
curl -X PATCH "https://api.zilomail.in/v1/calendar/events/ID" \
  -H "Authorization: Bearer $ZILO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
Answer · 200 OK
{
  "id": "string",
  "title": "string",
  "location": "string",
  "description": "string",
  "allDay": false,
  "start": "2026-10-17",
  "end": "2026-10-17",
  "recurring": false,
  "organizer": {
    "email": "string",
    "name": "string"
  },
  "mine": false,
  "guests": [
    {
      "email": "string",
      "name": "string",
      "answer": "NEEDS-ACTION"
    }
  ],
  "myAnswer": "string",
  "updatedAt": "2026-10-17T09:30:00.000Z"
}
Try it

Sign in to call it as yourself.

Remove an event#

DELETE/v1/calendar/events/{id}
calendar.write

Guests get a cancellation unless notifyGuests=false.

Path

idstringrequired
An id this API gave out. Up to 64 characters.

Query

notifyGuestsboolean
curl -X DELETE "https://api.zilomail.in/v1/calendar/events/ID" \
  -H "Authorization: Bearer $ZILO_TOKEN"

Answers 204 with no body.

Try it

Sign in to call it as yourself.