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

# Send Event

> Tell Minimo what happened, for example a new booking. The rules schedule the emails

Guide: [Booking events](https://docs.minimo.it/embedded/events.md#send-events-your-backend). Errors: [Errors and limits](https://docs.minimo.it/embedded/errors.md).


## OpenAPI

````yaml post /public/v1/events
openapi: 3.1.0
info:
  title: API Documentation
  description: Documentation for transactional and subscribe APIs
  version: 1.0.0
servers:
  - url: https://app.minimo.it
security:
  - bearerAuth: []
paths:
  /public/v1/events:
    servers:
      - url: https://api.minimo.it
    post:
      summary: Send event
      description: >-
        Tell Minimo what happened in your app, for example a new booking. The
        rules that listen to the event schedule their emails. Send the **full
        booking** on every event: a `booking.updated` replaces the details of
        the pending emails.


        The answer is `202`. Read `tenantAutomations` to see what was scheduled.
      operationId: sendEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                event:
                  type: string
                  description: Event name. Letters, digits, spaces and `.` `_` `:` `-`.
                  example: booking.created
                tenant:
                  type: string
                  description: >-
                    The restaurant. Its rules apply on top of the defaults, and
                    the guest belongs to it.
                  example: restaurant_4812
                email:
                  type: string
                  description: The guest. Or `contactId` or `phone`.
                  example: anna@example.com
                contactId:
                  type: integer
                  example: 4521
                phone:
                  type: string
                  example: '+393331234567'
                firstName:
                  type: string
                  example: Anna
                lastName:
                  type: string
                  example: Rossi
                payload:
                  type: object
                  description: >-
                    Any JSON. Each value is a merge variable of the email, by
                    its path in capitals (`booking.time` becomes
                    `BOOKING_TIME`). Dates **with their UTC offset**, else `422
                    INVALID_EVENT_DATE`.
                  example:
                    booking_at: '2026-11-20T20:30:00+01:00'
                    GUEST_NAME: Anna
                idempotencyKey:
                  type: string
                  description: >-
                    Your unique id of this event. Sent again, nothing happens
                    twice and `status` is `duplicate`.
                  example: booking-9921-created
                cancellationKey:
                  type: string
                  description: >-
                    Groups the emails of one object, for example the booking id.
                    A later `booking.cancelled` with the same key cancels them;
                    `booking.updated` moves them.
                  example: booking-9921
                marketingConsent:
                  type: boolean
                  description: >-
                    `true` records the guest's marketing consent to this
                    restaurant, also for a guest who exists, with the event as
                    evidence. Add details in `payload.consentEvidence`. An event
                    never withdraws a consent.
                from:
                  type: string
                  description: >-
                    Sender of the emails of this event: `"Name <address>"` or an
                    address under a verified domain of your workspace. Checked
                    now and again at send time.
                  example: Trattoria da Mario <bookings@yoursaas.example>
                replyTo:
                  type: string
                  description: Reply-To of the emails of this event. Any mailbox.
                  example: owner@trattoriadamario.example
              required:
                - event
            example:
              event: booking.created
              tenant: restaurant_4812
              email: anna@example.com
              firstName: Anna
              idempotencyKey: booking-9921-created
              cancellationKey: booking-9921
              marketingConsent: true
              payload:
                booking_at: '2026-11-20T20:30:00+01:00'
                GUEST_NAME: Anna
                BOOKING_TIME: '20:30'
                PARTY_SIZE: 4
      responses:
        '202':
          description: What was scheduled
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SendEventResponse'
              example:
                data:
                  event: booking.created
                  status: no_automation
                  automations: 0
                  contactId: 4521
                  tenantAutomations:
                    scheduled:
                      - id: 41
                        rule: confirmation
                        status: pending
                        reason: null
                        sendAt: '2026-11-08T18:00:01.000Z'
                      - id: 42
                        rule: reminder
                        status: pending
                        reason: null
                        sendAt: '2026-11-20T17:30:00.000Z'
                    cancelled: 0
                    rescheduled: 0
        '400':
          description: '`INVALID_PARAMETERS`: a field is not valid (also a wrong `tenant`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: >-
            `INVALID_TOKEN`: missing or wrong key, or a key without the
            **Events** permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: >-
            `INVALID_EVENT_DATE`: a date without its UTC offset. Sender errors:
            see [Errors and limits](/embedded/errors#sending).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - bearerAuth: []
      x-codeSamples:
        - label: cURL
          lang: bash
          source: |-
            curl --request POST \
              --url 'https://api.minimo.it/public/v1/events' \
              --header 'Authorization: Bearer YOUR_MINIMO_KEY' \
              --header 'Content-Type: application/json' \
              --data '{"event": "booking.created", "tenant": "restaurant_4812", "email": "anna@example.com", "firstName": "Anna", "idempotencyKey": "booking-9921-created", "cancellationKey": "booking-9921", "marketingConsent": true, "payload": {"booking_at": "2026-11-20T20:30:00+01:00", "GUEST_NAME": "Anna", "BOOKING_TIME": "20:30", "PARTY_SIZE": 4}}'
        - lang: JavaScript
          source: |-
            const res = await fetch('https://api.minimo.it/public/v1/events', {
              method: 'POST',
              headers: {
                Authorization: 'Bearer YOUR_MINIMO_KEY',
                'Content-Type': 'application/json',
              },
              body: JSON.stringify({"event": "booking.created", "tenant": "restaurant_4812", "email": "anna@example.com", "firstName": "Anna", "idempotencyKey": "booking-9921-created", "cancellationKey": "booking-9921", "marketingConsent": true, "payload": {"booking_at": "2026-11-20T20:30:00+01:00", "GUEST_NAME": "Anna", "BOOKING_TIME": "20:30", "PARTY_SIZE": 4}}),
            });
            const { data } = await res.json();
            console.log(data);
        - lang: Python
          source: |-
            import requests

            res = requests.post(
                'https://api.minimo.it/public/v1/events',
                headers={'Authorization': 'Bearer YOUR_MINIMO_KEY'},
                json={"event": "booking.created", "tenant": "restaurant_4812", "email": "anna@example.com", "firstName": "Anna", "idempotencyKey": "booking-9921-created", "cancellationKey": "booking-9921", "marketingConsent": True, "payload": {"booking_at": "2026-11-20T20:30:00+01:00", "GUEST_NAME": "Anna", "BOOKING_TIME": "20:30", "PARTY_SIZE": 4}},
            )
            print(res.status_code, res.text)
components:
  schemas:
    SendEventResponse:
      type: object
      properties:
        event:
          type: string
          example: booking.created
        status:
          type: string
          enum:
            - started
            - no_automation
            - no_contact
            - duplicate
          description: >-
            About workspace automations started by an event, not about the
            rules. Can say `no_automation` even when emails were scheduled: read
            `tenantAutomations`.
          example: no_automation
        automations:
          type: integer
          description: Workspace automations started.
          example: 0
        contactId:
          type: integer
          description: The guest.
          example: 4521
        tenantAutomations:
          type: object
          properties:
            scheduled:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                    nullable: true
                    description: Id of the scheduled send. `null` when nothing was stored.
                    example: 41
                  rule:
                    type: string
                    example: reminder
                  status:
                    type: string
                    enum:
                      - pending
                      - sending
                      - sent
                      - skipped
                      - duplicate
                      - unchanged
                    example: pending
                  reason:
                    type: string
                    nullable: true
                    description: Why it was skipped.
                  sendAt:
                    type: string
                    nullable: true
                    format: date-time
                    description: When it goes out.
                    example: '2026-11-20T17:30:00.000Z'
                required:
                  - id
                  - rule
                  - status
                  - reason
                  - sendAt
              description: One item per rule that matched the event.
            cancelled:
              type: integer
              description: Pending emails cancelled by this event.
              example: 0
            rescheduled:
              type: integer
              description: Pending emails moved by this event.
              example: 0
          required:
            - scheduled
            - cancelled
            - rescheduled
          description: >-
            What the rules scheduled, cancelled or moved. Present when a rule
            matched the event.
      required:
        - event
        - status
        - automations
    ApiError:
      type: object
      properties:
        status:
          type: string
          example: FAIL
        message:
          type: string
          description: The error code to test in your code.
          example: INVALID_PARAMETERS
        userMessage:
          type: string
          description: >-
            When present, a sentence that says what to fix. You can show or log
            it.
          example: Set the origins allowed to embed the widgets first.
      description: >-
        Every error has this shape. See [Errors and limits](/embedded/errors)
        for every code.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: mn-API_CLIENT_ID-API_KEY

````

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