---
title: "Create an event"
description: "Puts an event on the calendar, as New event does in the app, and invites the attendees."
url: "https://openemail.uk/docs/api/calendar/create"
area: "API"
category: "Mailbox"
---

# Create an event

Puts an event on the calendar, as New event does in the app, and invites the attendees.

`POST /calendar/events`

## POST /calendar/events

Puts an event on the calendar, as New event does in the app, and invites the attendees.

## Example

Needs `calendar:write`, and `emails:send` too when the event has attendees, because each of them gets an invitation by email from `from`.

**curl**

```
curl -X POST "$OE/calendar/events" -H "$AUTH" -H 'content-type: application/json' -d '{
  "summary": "Planning",
  "start": "2026-10-12T09:00:00Z",
  "end": "2026-10-12T09:30:00Z",
  "timezone": "Europe/London",
  "recurrence": "FREQ=WEEKLY;BYDAY=MO",
  "attendees": [{ "email": "ada@example.com", "name": "Ada" }],
  "reminders": [{ "minutesBefore": 10 }],
  "from": "team@acme.com"
}'
```

**Response**

```
{
  "object": "calendar_event",
  "id": "cal_3f9a1c7e5b2d48a06c1e9f4b",
  "uid": "5d2c8e1a-7b3f-4c9d-a6e2-1f8b0c4d7e93@openemail",
  "sequence": 0,
  "summary": "Planning",
  "description": null,
  "location": "Room 2",
  "url": null,
  "start": "2026-10-12T09:00:00.000Z",
  "end": "2026-10-12T09:30:00.000Z",
  "allDay": false,
  "timezone": "Europe/London",
  "recurrence": "FREQ=WEEKLY;BYDAY=MO",
  "exdates": [],
  "status": "CONFIRMED",
  "transparency": "OPAQUE",
  "visibility": "PUBLIC",
  "organizer": { "email": "team@acme.com", "name": null },
  "isOrganizer": true,
  "source": "local",
  "messageId": null,
  "threadId": null,
  "alarms": [{ "minutesBefore": 10, "action": "DISPLAY" }],
  "attendees": [
    {
      "object": "calendar_attendee",
      "email": "ada@example.com",
      "name": "Ada",
      "partstat": "NEEDS-ACTION",
      "role": "REQ-PARTICIPANT",
      "rsvp": true,
      "cutype": null,
      "respondedAt": null
    }
  ],
  "createdAt": "2026-10-02T14:03:11.000Z",
  "updatedAt": "2026-10-02T14:03:11.000Z"
}
```

> `from` has to be an address the key may send as, or the call is a 403 `from_address_forbidden`. An event with attendees and no `from` is a 422 `invalid_parameter`, unless `sendInvites` is false.

> `recurrence` takes an RRULE such as `FREQ=WEEKLY;BYDAY=MO`, and `reminders` up to five `{ minutesBefore }`.

## Reference

- [`POST /calendar/events`](https://openemail.uk/docs/api/reference/calendar#post-calendar-events): full reference