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

# Send event

> **Endpoint:** `v1/events`

Send an event to trigger automation workflows. Events are matched against workflow triggers based on the event name and optional conditions.

**Deduplication:**
Workflows have deduplication enabled by default with a 5-minute window. If the same event for the same email is sent within this time window, the duplicate event will be ignored and return a `deduplicated` status response. This prevents accidentally triggering the same workflow multiple times for the same user.

You can configure deduplication settings when creating workflows in the dashboard (up to 30 days maximum window).




## OpenAPI

````yaml api-reference/openapi.yml post /events
openapi: 3.1.0
info:
  title: Send Email API
  description: >
    Send transactional emails through MailDiver.


    ### Base URL

    All API endpoints are prefixed with `api.` subdomain:

    ```

    https://api.maildiver.com

    ```


    For the self-hosted version, if your domain is `example.com`:

    ```

    https://api.example.com

    ```


    ### Endpoint

    ```

    v1/emails

    ```


    ### Authentication

    All API requests require authentication using your API key in the
    Authorization header:

    ```

    Authorization: Bearer your-api-key

    ```
  version: 1.0.0
  license:
    name: MIT
servers:
  - url: https://api.maildiver.com/v1
    description: Production server
    variables:
      domain:
        default: yourdomain.com
        description: Your domain (without the api. prefix)
security:
  - bearerAuth: []
paths:
  /events:
    post:
      tags:
        - Automation Event
      summary: Send event
      description: >
        **Endpoint:** `v1/events`


        Send an event to trigger automation workflows. Events are matched
        against workflow triggers based on the event name and optional
        conditions.


        **Deduplication:**

        Workflows have deduplication enabled by default with a 5-minute window.
        If the same event for the same email is sent within this time window,
        the duplicate event will be ignored and return a `deduplicated` status
        response. This prevents accidentally triggering the same workflow
        multiple times for the same user.


        You can configure deduplication settings when creating workflows in the
        dashboard (up to 30 days maximum window).
      operationId: sendEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - event_name
                - email
              properties:
                event_name:
                  type: string
                  description: |
                    Name of the event to trigger.
                    - Required, non-empty string
                    - Maximum 100 characters
                    - Automatically normalized to lowercase and trimmed
                  maxLength: 100
                  example: user_signed_up
                email:
                  type: string
                  format: email
                  description: Contact's email address
                  maxLength: 255
                  example: recipient@example.com
                properties:
                  type: object
                  description: >
                    Event properties used for workflow condition matching and
                    email personalization.


                    **Workflow Conditions:**

                    Properties enable dynamic workflow branching based on
                    condition rules. Each property can be evaluated using:

                    - **Comparison:** `equals`, `not_equals`, `greater_than`,
                    `less_than`

                    - **Text matching:** `contains`, `not_contains`,
                    `begins_with`, `ends_with`

                    - **Existence:** `exists`, `not_exists`


                    Multiple rules can be combined with AND/OR logic for complex
                    conditions.


                    **Supported Types:**

                    - Strings: `"pro"`, `"landing_page"`

                    - Numbers: `99.99`, `1`

                    - Booleans: `true`, `false`

                    - Arrays: `["item1", "item2"]`


                    **Nested Properties:**

                    Use dot notation to access nested values (e.g.,
                    `"user.profile.tier"`).


                    **Example Use Case:**

                    Send different welcome emails based on subscription plan:

                    - If `plan equals "pro"` → send premium welcome email

                    - If `plan equals "free"` → send standard welcome email
                  example:
                    plan: pro
                    signup_source: landing_page
            examples:
              user_signup:
                summary: User signup event with nested properties
                value:
                  event_name: user_signed_up
                  email: user@example.com
                  properties:
                    user:
                      profile:
                        tier: pro
                        is_verified: true
                        credits: 100
                    signup_source: landing_page
                    referral_code: MAILDIVER2025
                    accepted_terms: true
              purchase_completed:
                summary: Purchase completed event with mixed types
                value:
                  event_name: purchase_completed
                  email: customer@example.com
                  properties:
                    amount: 99.99
                    currency: USD
                    product:
                      id: prod_123
                      name: Premium Plan
                      category: subscription
                    is_first_purchase: true
                    quantity: 1
                    discount_applied: false
      responses:
        '200':
          description: Event successfully processed or deduplicated
          content:
            application/json:
              examples:
                processed:
                  summary: Event processed successfully
                  value:
                    status: processed
                    event_id: 0199f234-d327-7cd8-9dc5-4fd8e5e249df
                    timestamp: '2024-03-15T10:30:45.123Z'
                deduplicated:
                  summary: Event deduplicated (already processed recently)
                  value:
                    status: deduplicated
                    original_event_id: 0199f234-d327-7cd8-9dc5-4fd8e5e249df
                    timestamp: '2024-03-15T10:30:45.123Z'
                    deduplication_window_seconds: 300
        '400':
          description: Bad request
          content:
            application/json:
              examples:
                missingField:
                  summary: Missing required field
                  value:
                    message: event_name is required
                tooLong:
                  summary: Event name too long
                  value:
                    message: 'event_name is too long: 150. Max length is 100'
                invalidEmail:
                  summary: Invalid email format
                  value:
                    message: Invalid email format
        '403':
          description: Forbidden (API key is missing or invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No active workflows found for this event
          content:
            application/json:
              examples:
                noWorkflows:
                  summary: No workflows configured for event
                  value:
                    error: NO_WORKFLOWS_FOUND
                    message: No active workflows configured for event 'user_signed_up'
                    event_name: user_signed_up
components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
          description: Error description
      description: |
        Error response with message.

        ### Common Errors

        #### 400 Bad Request
        Validation errors return only the error message:
        ```json
        {
          "message": "from field is required"
        }
        ```

        Common validation messages:
        - `"from field is required"`
        - `"to field is required"`
        - `"subject field is required"`
        - `"html content size (42MB) exceeds maximum of 40MB"`
        - `"Too many recipients: 51. Maximum allowed is 50"`
        - `"Invalid email format in from field"`
        - `"template_id cannot be used together with html"`

        #### 403 Forbidden
        Authentication errors include both message and code:
        ```json
        {
          "message": "Invalid API key",
          "code": "invalid_api_key"
        }
        ```
        ```json
        {
          "message": "Invalid authorization header",
          "code": "invalid_authorization_header"
        }
        ```

        #### 404 Not Found
        ```json
        {
          "message": "Template 'welcome-email' not found"
        }
        ```
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key with format "Bearer {your-api-key}"

````