> ## Documentation Index
> Fetch the complete documentation index at: https://cal.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Invite guests to an Event

> Emails an invitation to each address. Addresses that are already invited or registered are skipped, and the response reports what happened to every address. The Event must be published, not cancelled and not started yet, and the authenticated user must have a verified email. An Event holds at most 200 active invitations. The authenticated user must be the Event's owner, one of its hosts, an accepted co-host, or a member of the owning team. PBAC permission for team events: `calEvent.update`. If accessed using an OAuth access token, the `EVENT_WRITE` scope is required.



## OpenAPI

````yaml /api-reference/v2/openapi.json post /v2/events/{uuid}/invitations
openapi: 3.0.0
info:
  title: Cal.com API v2
  description: ''
  version: 1.0.0
  contact: {}
servers: []
security: []
tags: []
paths:
  /v2/events/{uuid}/invitations:
    post:
      tags:
        - Events
      summary: Invite guests to an Event
      description: >-
        Emails an invitation to each address. Addresses that are already invited
        or registered are skipped, and the response reports what happened to
        every address. The Event must be published, not cancelled and not
        started yet, and the authenticated user must have a verified email. An
        Event holds at most 200 active invitations. The authenticated user must
        be the Event's owner, one of its hosts, an accepted co-host, or a member
        of the owning team. PBAC permission for team events: `calEvent.update`.
        If accessed using an OAuth access token, the `EVENT_WRITE` scope is
        required.
      operationId: EventInvitationsController_inviteGuests
      parameters:
        - name: uuid
          required: true
          in: path
          description: >-
            Event UUID. Accepts the canonical UUID (e.g.
            `018ff5cd-6dc4-7d57-bcbc-374702ca8b38`) or its short-uuid (Flickr
            Base58) form (e.g. `1cbZYoAFoJdwqN4tixezd5`).
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: >-
            value must be `Bearer <token>` where `<token>` is api key prefixed
            with cal_, managed user access token, or OAuth access token
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteGuestsInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteGuestsOutputResponseDto'
        '400':
          description: >-
            Invalid Event UUID or body, the Event is unpublished, cancelled or
            started, or the invitation limit is reached
        '401':
          description: Unauthenticated
        '403':
          description: Insufficient permissions, or the user's email is not verified
        '404':
          description: Event not found
        '429':
          description: Rate limit exceeded
components:
  schemas:
    InviteGuestsInput:
      type: object
      properties:
        emails:
          minItems: 1
          description: Email addresses to invite. Between 1 and 200 per request.
          example:
            - guest@example.com
          type: array
          items:
            type: string
            format: email
        hostNote:
          type: string
          maxLength: 500
          description: A personal note from the host, included in the invitation email.
      required:
        - emails
    InviteGuestsOutputResponseDto:
      type: object
      properties:
        status:
          enum:
            - success
            - error
          type: string
          example: success
        data:
          $ref: '#/components/schemas/InviteGuestsOutputDto'
      required:
        - status
        - data
    InviteGuestsOutputDto:
      type: object
      properties:
        invitedCount:
          type: number
        skippedAlreadyInvited:
          type: number
        skippedAlreadyRegistered:
          type: number
        skippedOnCooldown:
          type: number
        skippedInvalid:
          type: number
        failedCount:
          type: number
          description: Addresses whose invitation could not be saved. They can be retried.
        outcomes:
          description: One entry per submitted address.
          type: array
          items:
            $ref: '#/components/schemas/InviteOutcomeOutputDto'
      required:
        - invitedCount
        - skippedAlreadyInvited
        - skippedAlreadyRegistered
        - skippedOnCooldown
        - skippedInvalid
        - failedCount
        - outcomes
    InviteOutcomeOutputDto:
      type: object
      properties:
        email:
          type: string
        reason:
          enum:
            - invited
            - already-invited
            - already-registered
            - cooldown
            - invalid-format
            - undeliverable
            - duplicate
            - failed
          type: string
          description: >-
            What happened to this address: `invited`; skipped as
            `already-invited`, `already-registered` or `cooldown` (re-invited
            too recently); rejected as `invalid-format`, `undeliverable` or
            `duplicate` (repeated in this request); or `failed`, which can be
            retried.
      required:
        - email
        - reason

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.