---
title: "Create a calendar event"
method: POST
path: "/v1/inboxes/{inbox_id}/calendar/events"
tags: ["Calendar"]
---

# Create a calendar event

`POST /v1/inboxes/{inbox_id}/calendar/events`

## Request

- Base URL: `https://api.deadsimple.email`
- URL: `https://api.deadsimple.email/v1/inboxes/{inbox_id}/calendar/events`
- Auth: HTTP bearer

Puts an event on the inbox's calendar. Nothing is sent: call `invite` to send it to the attendees as a real invitation. The inbox is the organizer unless `organizer` says otherwise. Emits `calendar.event.created`. SDK: `calendar.create`.

## Path parameters

- `inbox_id` string, required

## Request body

- object: Fields for creating or (all optional, on PATCH) updating an event. Times are ISO 8601 and need a zone: a trailing Z, an offset, or `timezone`. A bare date makes an all-day event. Stored and returned as UTC instants.
  - `title` string, required
  - `start` string, required: "2026-09-15T15:00:00Z", "2026-09-15T15:00:00-04:00", "2026-09-15T15:00:00" plus timezone, or "2026-09-15".
  - `end` string: Omit to use duration_minutes (default 30). On PATCH, a moved start keeps the event's length.
  - `duration_minutes` integer
  - `timezone` string: IANA zone for a local start/end with no offset, e.g. America/New_York. Also sets X-WR-TIMEZONE on the feed.
  - `all_day` boolean
  - `description` string
  - `location` string
  - `status` 'confirmed' | 'tentative' | 'cancelled'
  - `organizer` CalendarOrganizer
    - `email` string, email
    - `name` string
  - `attendees` union[]
    - union
      - string, email
      - CalendarAttendee
        - `email` string, email, required
        - `name` string
        - `response` 'needs-action' | 'accepted' | 'declined' | 'tentative': The attendee's answer as last seen (our own rsvp, or their REPLY).
        - `optional` boolean: OPT-PARTICIPANT rather than REQ-PARTICIPANT on the invitation.
  - `ical_uid` string: Create only. Supply your own iCalendar UID; otherwise one is generated as {hex}@deadsimple.email.
  - `sequence` integer: iCalendar SEQUENCE. Managed for you; set it only to take over from a calendar system that already sent this event.

## Response `201`

The event.

- CalendarEvent
  - `event_id` string
  - `inbox_id` string
  - `workspace_id` string, nullable
  - `ical_uid` string: Stable across updates. What an update, cancellation or reply is matched on, on both ends.
  - `title` string
  - `description` string
  - `location` string
  - `start_at` string: ISO 8601 UTC, e.g. 2026-09-15T19:00:00Z
  - `end_at` string: ISO 8601 UTC. Exclusive for all-day events.
  - `timezone` string
  - `all_day` boolean
  - `status` 'confirmed' | 'tentative' | 'cancelled'
  - `organizer` CalendarOrganizer
    - `email` string, email
    - `name` string
  - `attendees` CalendarAttendee[]
    - `email` string, email, required
    - `name` string
    - `response` 'needs-action' | 'accepted' | 'declined' | 'tentative': The attendee's answer as last seen (our own rsvp, or their REPLY).
    - `optional` boolean: OPT-PARTICIPANT rather than REQ-PARTICIPANT on the invitation.
  - `source` 'api' | 'sent' | 'inbound': api = created here; sent = created here and sent as an invitation; inbound = arrived by email.
  - `sequence` integer
  - `message_id` string, nullable: The invitation we sent, or the inbound message that last created, updated or cancelled the event.
  - `invited_at` string, nullable
  - `created_at` string
  - `updated_at` string

## Other responses

- `400`: Missing title or start, a naive time with no timezone, an unknown zone, end before start, or a duplicate ical_uid on this inbox.

---

[API](https://skmtc.dev/deadsimple/apis/dead-simple-email-api.md) · [All operations](https://skmtc.dev/deadsimple/apis/dead-simple-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/deadsimple/apis/dead-simple-email-api/revisions/c697881be131?raw)