---
title: "Create calendar"
method: POST
path: "/v1/calendars"
tags: ["Calendars"]
---

# Create calendar

`POST /v1/calendars`

## Request

- Base URL: `https://api.forwardemail.net`
- URL: `https://api.forwardemail.net/v1/calendars`
- Auth: HTTP basic

Create a new calendar. The calendar name is required, while other properties like color, timezone, and description are optional. If a calendar with the same name already exists, a conflict error will be returned.

## Request body

- CalendarInput
  - `name` string, required: Calendar name
  - `calendar_id` string: Custom calendar ID (if not provided, will be auto-generated)
  - `description` string: Calendar description
  - `color` string: Calendar color (hex format, if not provided, will be auto-generated)
  - `timezone` string: Calendar timezone (defaults to user's timezone or UTC)
  - `order` integer: Calendar display order (defaults to 0)

## Response `201`

Calendar created successfully

- Calendar
  - `id` string, required: Calendar ID (calendarId from CalDAV)
  - `name` string, required: Calendar name
  - `description` string, required: Calendar description
  - `color` string, required: Calendar color (hex format)
  - `timezone` string, required: Calendar timezone
  - `order` integer, required: Calendar display order
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `object` 'calendar', required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `409`: Conflict
- `500`: Internal Server Error

---

[API](https://skmtc.dev/forwardemail/apis/forward-email-api.md) · [All operations](https://skmtc.dev/forwardemail/apis/forward-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/forwardemail/apis/forward-email-api/revisions/ecefab4527f6?raw)