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

# List Scheduled Emails

> List the scheduled emails of your team, newest first. Requires the `emails:read` scope.

This endpoint is new: listing was previously impossible because SparkPost's transmission list endpoint returns 404. Lettr now holds scheduled emails in its own store, so they can be listed, read back and cancelled at any point before they are injected.

A sandbox key only sees the emails it scheduled itself.

List emails waiting to be sent, soonest delivery time first. Filter by `status` to see only what is still pending, or to find what was cancelled or failed.

Each row carries the same detail as a single read, including the `sch_` request ID you need to get or cancel an individual email.


## OpenAPI

````yaml GET /emails/scheduled
openapi: 3.1.0
info:
  title: Lettr API
  version: 1.0.0
  description: >-
    Lettr Email API - Send transactional emails with tracking, attachments, and
    personalization.
  contact:
    name: Lettr Support
    url: https://lettr.com
  license:
    name: Proprietary
    url: https://lettr.com/terms
servers:
  - url: https://app.lettr.com/api
    description: Production
security: []
tags:
  - name: Emails
    description: Email sending operations
  - name: Templates
    description: Email template management operations
  - name: Domains
    description: Domain management operations
  - name: Webhooks
    description: Webhook management operations
  - name: Audience
    description: 'Audience management: lists, contacts, topics, properties, and segments'
  - name: Campaigns
    description: >-
      Campaign operations: listing, stats, engagement events, and
      dispatch/scheduling
paths:
  /emails/scheduled:
    get:
      tags:
        - Emails
      summary: List Scheduled Emails
      description: >-
        List the scheduled emails of your team, newest first. Requires the
        `emails:read` scope.


        This endpoint is new: listing was previously impossible because
        SparkPost's transmission list endpoint returns 404. Lettr now holds
        scheduled emails in its own store, so they can be listed, read back and
        cancelled at any point before they are injected.


        A sandbox key only sees the emails it scheduled itself.
      operationId: listScheduledEmails
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - scheduled
              - sending
              - sent
              - cancelled
              - failed
          description: Filter by scheduled email state
        - name: per_page
          in: query
          description: Number of results per page (1-100). Defaults to 25.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: page
          in: query
          description: Page number. Defaults to 1.
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
      responses:
        '200':
          description: Scheduled emails retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListScheduledEmailsResponse'
              example:
                message: Scheduled emails retrieved successfully.
                data:
                  scheduled_emails:
                    - request_id: sch_01JQZ3N2K8XW9V6M4TBRC7YHDE
                      transmission_id: null
                      state: scheduled
                      scheduled_at: '2024-01-16T10:00:00Z'
                      from: sender@example.com
                      from_name: Sender Name
                      subject: Scheduled Newsletter
                      recipients:
                        - recipient@example.com
                      num_recipients: 1
                      accepted: 1
                      rejected: 0
                      tag: null
                      failure_reason: null
                      events: []
                  pagination:
                    total: 1
                    per_page: 25
                    current_page: 1
                    last_page: 1
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              example:
                message: Validation failed.
                error_code: validation_error
                errors:
                  per_page:
                    - The per_page parameter must not exceed 100.
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Failed to list scheduled emails. Please try again later.
                error_code: retrieval_error
      security:
        - bearerAuth: []
components:
  schemas:
    ListScheduledEmailsResponse:
      type: object
      required:
        - message
        - data
      properties:
        message:
          type: string
        data:
          type: object
          required:
            - scheduled_emails
            - pagination
          properties:
            scheduled_emails:
              type: array
              items:
                $ref: '#/components/schemas/ScheduledEmailResponse'
            pagination:
              $ref: '#/components/schemas/ScheduledEmailsPagination'
    ValidationErrorResponse:
      type: object
      required:
        - message
        - error_code
        - errors
      properties:
        message:
          type: string
          description: Human-readable error message
          example: Validation failed.
        error_code:
          type: string
          description: Error code (always `validation_error` for 422 responses)
          const: validation_error
          example: validation_error
        errors:
          type: object
          description: Field-specific validation errors
          additionalProperties:
            type: array
            items:
              type: string
          example:
            from:
              - The sender email address is required.
            to:
              - At least one recipient email address is required.
    ErrorResponse:
      type: object
      required:
        - message
        - error_code
      description: Error response for non-validation errors (400, 409, 500, 502).
      properties:
        message:
          type: string
          description: Human-readable error message
          example: The sender domain could not be determined from the email address.
        error_code:
          $ref: '#/components/schemas/ErrorCode'
    ScheduledEmailResponse:
      type: object
      description: >-
        A scheduled email held by Lettr. This is the `data` object of `POST
        /emails/scheduled`, `GET /emails/scheduled/{transmissionId}` and `DELETE
        /emails/scheduled/{transmissionId}`, and each entry of
        `scheduled_emails` in `GET /emails/scheduled`.


        **Breaking change.** Scheduled emails are no longer parked inside
        SparkPost with `options.start_time` — SparkPost retired its
        per-transmission GET and DELETE endpoints. Lettr now holds the email in
        its own store and injects it into SparkPost when it is due, so
        `request_id` is Lettr's own `sch_...` id, `transmission_id` is a
        separate field that stays `null` until injection, and `state` values are
        Lettr's own rather than SparkPost's pass-through states.
      required:
        - request_id
        - transmission_id
        - state
        - scheduled_at
        - from
        - from_name
        - subject
        - recipients
        - num_recipients
        - accepted
        - rejected
        - tag
        - failure_reason
        - events
      properties:
        request_id:
          type: string
          description: >-
            Lettr's identifier for the scheduled email, prefixed `sch_`. Pass
            this value to `GET` and `DELETE /emails/scheduled/{transmissionId}`.
            Before this change the field held SparkPost's transmission id.
          example: sch_01JQZ3N2K8XW9V6M4TBRC7YHDE
        transmission_id:
          type:
            - string
            - 'null'
          description: >-
            SparkPost's transmission id. `null` until the email is injected into
            SparkPost at its delivery time. This is the value that appears as
            `transmission_id` on your webhook events, so correlate webhooks on
            this field — not on `request_id`.
          example: '12345678901234567890'
        state:
          type: string
          description: >-
            Current state of the scheduled email. `scheduled` — waiting for its
            delivery time, the only state that can be cancelled. `sending` —
            claimed by the dispatcher and being injected right now. `sent` —
            injected into SparkPost; delivery detail then comes from `events`.
            `cancelled` — cancelled before injection, never handed to SparkPost.
            `failed` — injection was attempted and gave up, see
            `failure_reason`.
          enum:
            - scheduled
            - sending
            - sent
            - cancelled
            - failed
          example: scheduled
        scheduled_at:
          type: string
          format: date-time
          description: The delivery time in ISO 8601 format (UTC).
          example: '2024-01-16T10:00:00Z'
        from:
          type: string
          format: email
          description: Sender email address.
          example: sender@example.com
        from_name:
          type:
            - string
            - 'null'
          description: Sender display name.
          example: Sender Name
        subject:
          type:
            - string
            - 'null'
          description: Email subject line.
          example: Scheduled Newsletter
        recipients:
          type: array
          items:
            type: string
            format: email
          description: List of recipient email addresses.
          example:
            - recipient@example.com
        num_recipients:
          type: integer
          minimum: 0
          description: Total number of recipients.
          example: 1
        accepted:
          type: integer
          minimum: 0
          description: >-
            Number of recipients accepted for delivery. Before injection this is
            what Lettr accepted; afterwards it is SparkPost's own count.
          example: 1
        rejected:
          type: integer
          minimum: 0
          description: Number of recipients rejected. `0` before injection.
          example: 0
        tag:
          type:
            - string
            - 'null'
          description: >-
            Tag supplied when the email was scheduled, used for tracking and
            analytics.
          example: welcome-series-2024
        failure_reason:
          type:
            - string
            - 'null'
          description: Why injection gave up. Only set when `state` is `failed`.
          example: null
        events:
          type: array
          description: >-
            Delivery events for this email. Empty until the email has been sent;
            populated with injection, delivery, bounce, open, click and other
            events once it has been injected into SparkPost.
          items:
            $ref: '#/components/schemas/EmailEvent'
    ScheduledEmailsPagination:
      type: object
      required:
        - total
        - per_page
        - current_page
        - last_page
      properties:
        total:
          type: integer
        per_page:
          type: integer
        current_page:
          type: integer
        last_page:
          type: integer
    UnauthorizedResponse:
      type: object
      required:
        - message
      description: Error response for authentication failures (401).
      properties:
        message:
          type: string
          description: Human-readable error message
          example: API key is required.
    ErrorCode:
      type: string
      description: >-
        Error codes returned by the API.


        | Code | HTTP Status | Description |

        |------|-------------|-------------|

        | `validation_error` | 422 | Request validation failed. Check the
        `errors` object for field-specific messages. |

        | `invalid_domain` | 400 | The sender domain could not be determined
        from the email address. |

        | `unconfigured_domain` | 400 | The sender domain is not configured or
        approved for sending. |

        | `send_error` | 400, 500 | General error during email send preparation
        or domain registration. |

        | `retrieval_error` | 400, 500 | Failed to retrieve resources (e.g.,
        sandbox key without associated user, upstream error). |

        | `transmission_failed` | 502 | Email transmission to the upstream
        provider failed. |

        | `resource_already_exists` | 409 | The resource (e.g., domain) already
        exists. |

        | `not_found` | 404 | The specified resource was not found. |

        | `template_not_found` | 404 | The specified template, project, or
        template version was not found. |

        | `insufficient_scope` | 403 | The API key does not have the required
        scope for this endpoint. |

        | `schedule_cancellation_failed` | 409, 500 | The scheduled email can no
        longer be cancelled (already sent, already cancelled, or being injected
        right now), or the cancellation itself failed. |

        | `quota_exceeded` | 429 | Monthly sending quota exceeded. Upgrade your
        plan to continue sending. |

        | `daily_quota_exceeded` | 429 | Daily sending quota exceeded. Try again
        tomorrow. |

        | `campaign_not_sendable` | 422 | The campaign cannot be sent in its
        current state (not a draft, or missing subject/sender/content). |

        | `campaign_not_scheduled` | 422 | The campaign is not scheduled, so it
        cannot be unscheduled. |
      enum:
        - validation_error
        - idempotency_key_conflict
        - idempotency_in_progress
        - invalid_domain
        - unconfigured_domain
        - send_error
        - retrieval_error
        - transmission_failed
        - resource_already_exists
        - not_found
        - template_not_found
        - insufficient_scope
        - schedule_cancellation_failed
        - quota_exceeded
        - daily_quota_exceeded
        - campaign_not_sendable
        - campaign_not_scheduled
      example: invalid_domain
    EmailEvent:
      description: >-
        An email event. The `type` field determines which additional fields are
        present. All event types share common fields defined in
        `CommonEventProperties`.
      oneOf:
        - $ref: '#/components/schemas/InjectionEvent'
        - $ref: '#/components/schemas/DeliveryEvent'
        - $ref: '#/components/schemas/BounceEvent'
        - $ref: '#/components/schemas/DelayEvent'
        - $ref: '#/components/schemas/OutOfBandEvent'
        - $ref: '#/components/schemas/SpamComplaintEvent'
        - $ref: '#/components/schemas/PolicyRejectionEvent'
        - $ref: '#/components/schemas/ClickEvent'
        - $ref: '#/components/schemas/OpenEvent'
        - $ref: '#/components/schemas/InitialOpenEvent'
        - $ref: '#/components/schemas/AmpClickEvent'
        - $ref: '#/components/schemas/AmpOpenEvent'
        - $ref: '#/components/schemas/AmpInitialOpenEvent'
        - $ref: '#/components/schemas/GenerationFailureEvent'
        - $ref: '#/components/schemas/GenerationRejectionEvent'
        - $ref: '#/components/schemas/ListUnsubscribeEvent'
        - $ref: '#/components/schemas/LinkUnsubscribeEvent'
      discriminator:
        propertyName: type
        mapping:
          injection:
            $ref: '#/components/schemas/InjectionEvent'
          delivery:
            $ref: '#/components/schemas/DeliveryEvent'
          bounce:
            $ref: '#/components/schemas/BounceEvent'
          delay:
            $ref: '#/components/schemas/DelayEvent'
          out_of_band:
            $ref: '#/components/schemas/OutOfBandEvent'
          spam_complaint:
            $ref: '#/components/schemas/SpamComplaintEvent'
          policy_rejection:
            $ref: '#/components/schemas/PolicyRejectionEvent'
          click:
            $ref: '#/components/schemas/ClickEvent'
          open:
            $ref: '#/components/schemas/OpenEvent'
          initial_open:
            $ref: '#/components/schemas/InitialOpenEvent'
          amp_click:
            $ref: '#/components/schemas/AmpClickEvent'
          amp_open:
            $ref: '#/components/schemas/AmpOpenEvent'
          amp_initial_open:
            $ref: '#/components/schemas/AmpInitialOpenEvent'
          generation_failure:
            $ref: '#/components/schemas/GenerationFailureEvent'
          generation_rejection:
            $ref: '#/components/schemas/GenerationRejectionEvent'
          list_unsubscribe:
            $ref: '#/components/schemas/ListUnsubscribeEvent'
          link_unsubscribe:
            $ref: '#/components/schemas/LinkUnsubscribeEvent'
    InjectionEvent:
      description: Fired when a message is received by the system and queued for delivery.
      allOf:
        - $ref: '#/components/schemas/CommonEventProperties'
        - type: object
          properties:
            type:
              type: string
              enum:
                - injection
            initial_pixel:
              type:
                - boolean
                - 'null'
              description: Whether initial open tracking pixel was included
    DeliveryEvent:
      description: >-
        Fired when a message is successfully delivered to the recipient's mail
        server.
      allOf:
        - $ref: '#/components/schemas/CommonEventProperties'
        - type: object
          properties:
            type:
              type: string
              enum:
                - delivery
            queue_time:
              type:
                - integer
                - 'null'
              description: Time spent in queue in milliseconds
              example: 1845
            outbound_tls:
              type:
                - string
                - 'null'
              description: Whether TLS was used for outbound delivery ("1" = yes)
              example: '1'
    BounceEvent:
      description: >-
        Fired when a message is permanently rejected by the recipient's mail
        server.
      allOf:
        - $ref: '#/components/schemas/CommonEventProperties'
        - type: object
          properties:
            type:
              type: string
              enum:
                - bounce
            bounce_class:
              type:
                - integer
                - 'null'
              description: >-
                Bounce classification code (e.g. 10 = Invalid Recipient, 30 =
                Generic Bounce)
              example: 10
            error_code:
              type:
                - string
                - 'null'
              description: SMTP error code
              example: '550'
            reason:
              type:
                - string
                - 'null'
              description: Human-readable bounce reason
              example: >-
                550 5.1.1 The email account that you tried to reach does not
                exist.
            raw_reason:
              type:
                - string
                - 'null'
              description: Raw SMTP reason string
              example: 550 5.1.1 User unknown
            num_retries:
              type:
                - integer
                - 'null'
              description: Number of delivery retries attempted
            device_token:
              type:
                - string
                - 'null'
              description: Device token if applicable
    DelayEvent:
      description: Fired when a message delivery is temporarily delayed (will be retried).
      allOf:
        - $ref: '#/components/schemas/CommonEventProperties'
        - type: object
          properties:
            type:
              type: string
              enum:
                - delay
            reason:
              type:
                - string
                - 'null'
              description: Human-readable delay reason
            raw_reason:
              type:
                - string
                - 'null'
              description: Raw SMTP reason string
            error_code:
              type:
                - string
                - 'null'
              description: SMTP error code
              example: '421'
            bounce_class:
              type:
                - integer
                - 'null'
              description: Bounce classification code
            num_retries:
              type:
                - integer
                - 'null'
              description: Number of delivery retries attempted so far
            queue_time:
              type:
                - integer
                - 'null'
              description: Time spent in queue in milliseconds
            outbound_tls:
              type:
                - string
                - 'null'
              description: Whether TLS was used for outbound delivery
    OutOfBandEvent:
      description: >-
        Fired when a remote mail server sends an asynchronous bounce after
        initially accepting the message.
      allOf:
        - $ref: '#/components/schemas/CommonEventProperties'
        - type: object
          properties:
            type:
              type: string
              enum:
                - out_of_band
            bounce_class:
              type:
                - integer
                - 'null'
              description: Bounce classification code
            error_code:
              type:
                - string
                - 'null'
              description: SMTP error code
            reason:
              type:
                - string
                - 'null'
              description: Human-readable bounce reason
            raw_reason:
              type:
                - string
                - 'null'
              description: Raw SMTP reason string
            device_token:
              type:
                - string
                - 'null'
              description: Device token if applicable
    SpamComplaintEvent:
      description: Fired when a recipient marks the message as spam via a feedback loop.
      allOf:
        - $ref: '#/components/schemas/CommonEventProperties'
        - type: object
          properties:
            type:
              type: string
              enum:
                - spam_complaint
            fbtype:
              type:
                - string
                - 'null'
              description: Feedback type (e.g. "abuse")
              example: abuse
            report_by:
              type:
                - string
                - 'null'
              description: Who reported the spam
            report_to:
              type:
                - string
                - 'null'
              description: Where the spam report was sent
    PolicyRejectionEvent:
      description: >-
        Fired when a message is rejected due to policy (e.g. suppression list,
        rate limiting).
      allOf:
        - $ref: '#/components/schemas/CommonEventProperties'
        - type: object
          properties:
            type:
              type: string
              enum:
                - policy_rejection
            remote_addr:
              type:
                - string
                - 'null'
              description: Remote IP address
            reason:
              type:
                - string
                - 'null'
              description: Human-readable rejection reason
            raw_reason:
              type:
                - string
                - 'null'
              description: Raw rejection reason
            error_code:
              type:
                - string
                - 'null'
              description: Error code
            bounce_class:
              type:
                - integer
                - 'null'
              description: Bounce classification code
    ClickEvent:
      description: Fired when a recipient clicks a tracked link in the email.
      allOf:
        - $ref: '#/components/schemas/CommonEventProperties'
        - type: object
          properties:
            type:
              type: string
              enum:
                - click
            target_link_url:
              type:
                - string
                - 'null'
              description: The URL that was clicked
              example: https://example.com/reset-password?token=abc123
            target_link_name:
              type:
                - string
                - 'null'
              description: The name/label of the clicked link
            user_agent:
              type:
                - string
                - 'null'
              description: Raw user agent string
              example: >-
                Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)
                AppleWebKit/537.36
            user_agent_parsed:
              $ref: '#/components/schemas/UserAgentParsed'
            geo_ip:
              $ref: '#/components/schemas/GeoIp'
            ip_address:
              type:
                - string
                - 'null'
              description: IP address of the click
              example: 104.28.114.11
    OpenEvent:
      description: >-
        Fired when a recipient opens the email (subsequent opens after the
        initial open).
      allOf:
        - $ref: '#/components/schemas/CommonEventProperties'
        - type: object
          properties:
            type:
              type: string
              enum:
                - open
            user_agent:
              type:
                - string
                - 'null'
              description: Raw user agent string
              example: Mozilla/5.0
            user_agent_parsed:
              $ref: '#/components/schemas/UserAgentParsed'
            geo_ip:
              $ref: '#/components/schemas/GeoIp'
            ip_address:
              type:
                - string
                - 'null'
              description: IP address of the open
              example: 104.28.114.11
            initial_pixel:
              type:
                - boolean
                - 'null'
              description: Whether this was triggered by the initial tracking pixel
    InitialOpenEvent:
      description: Fired the first time a recipient opens the email.
      allOf:
        - $ref: '#/components/schemas/CommonEventProperties'
        - type: object
          properties:
            type:
              type: string
              enum:
                - initial_open
            user_agent:
              type:
                - string
                - 'null'
              description: Raw user agent string
              example: Mozilla/5.0
            user_agent_parsed:
              $ref: '#/components/schemas/UserAgentParsed'
            geo_ip:
              $ref: '#/components/schemas/GeoIp'
            ip_address:
              type:
                - string
                - 'null'
              description: IP address of the open
              example: 104.28.114.11
            initial_pixel:
              type:
                - boolean
                - 'null'
              description: Whether this was triggered by the initial tracking pixel
    AmpClickEvent:
      description: Fired when a recipient clicks a tracked link in an AMP email.
      allOf:
        - $ref: '#/components/schemas/CommonEventProperties'
        - type: object
          properties:
            type:
              type: string
              enum:
                - amp_click
            target_link_url:
              type:
                - string
                - 'null'
              description: The URL that was clicked
            target_link_name:
              type:
                - string
                - 'null'
              description: The name/label of the clicked link
            user_agent:
              type:
                - string
                - 'null'
              description: Raw user agent string
            user_agent_parsed:
              $ref: '#/components/schemas/UserAgentParsed'
            geo_ip:
              $ref: '#/components/schemas/GeoIp'
            ip_address:
              type:
                - string
                - 'null'
              description: IP address of the click
    AmpOpenEvent:
      description: Fired when a recipient opens an AMP email (subsequent opens).
      allOf:
        - $ref: '#/components/schemas/CommonEventProperties'
        - type: object
          properties:
            type:
              type: string
              enum:
                - amp_open
            user_agent:
              type:
                - string
                - 'null'
              description: Raw user agent string
            user_agent_parsed:
              $ref: '#/components/schemas/UserAgentParsed'
            geo_ip:
              $ref: '#/components/schemas/GeoIp'
            ip_address:
              type:
                - string
                - 'null'
              description: IP address of the open
            initial_pixel:
              type:
                - boolean
                - 'null'
              description: Whether this was triggered by the initial tracking pixel
    AmpInitialOpenEvent:
      description: Fired the first time a recipient opens an AMP email.
      allOf:
        - $ref: '#/components/schemas/CommonEventProperties'
        - type: object
          properties:
            type:
              type: string
              enum:
                - amp_initial_open
            user_agent:
              type:
                - string
                - 'null'
              description: Raw user agent string
            user_agent_parsed:
              $ref: '#/components/schemas/UserAgentParsed'
            geo_ip:
              $ref: '#/components/schemas/GeoIp'
            ip_address:
              type:
                - string
                - 'null'
              description: IP address of the open
            initial_pixel:
              type:
                - boolean
                - 'null'
              description: Whether this was triggered by the initial tracking pixel
    GenerationFailureEvent:
      description: >-
        Fired when the system fails to generate a message (e.g. template
        rendering error).
      allOf:
        - $ref: '#/components/schemas/CommonEventProperties'
        - type: object
          properties:
            type:
              type: string
              enum:
                - generation_failure
            reason:
              type:
                - string
                - 'null'
              description: Human-readable failure reason
            raw_reason:
              type:
                - string
                - 'null'
              description: Raw failure reason
            error_code:
              type:
                - string
                - 'null'
              description: Error code
    GenerationRejectionEvent:
      description: >-
        Fired when the system rejects message generation (e.g. policy
        violation).
      allOf:
        - $ref: '#/components/schemas/CommonEventProperties'
        - type: object
          properties:
            type:
              type: string
              enum:
                - generation_rejection
            reason:
              type:
                - string
                - 'null'
              description: Human-readable rejection reason
            raw_reason:
              type:
                - string
                - 'null'
              description: Raw rejection reason
            error_code:
              type:
                - string
                - 'null'
              description: Error code
    ListUnsubscribeEvent:
      description: Fired when a recipient uses the List-Unsubscribe header to unsubscribe.
      allOf:
        - $ref: '#/components/schemas/CommonEventProperties'
        - type: object
          properties:
            type:
              type: string
              enum:
                - list_unsubscribe
    LinkUnsubscribeEvent:
      description: Fired when a recipient clicks an unsubscribe link in the email body.
      allOf:
        - $ref: '#/components/schemas/CommonEventProperties'
        - type: object
          properties:
            type:
              type: string
              enum:
                - link_unsubscribe
    CommonEventProperties:
      type: object
      required:
        - event_id
        - type
        - timestamp
        - request_id
        - rcpt_to
        - raw_rcpt_to
        - recipient_domain
        - mailbox_provider
        - mailbox_provider_region
      properties:
        event_id:
          type: string
          description: Unique identifier for the event
          example: '7609871845907017144'
        type:
          type: string
          description: The event type
          enum:
            - injection
            - delivery
            - bounce
            - delay
            - out_of_band
            - spam_complaint
            - policy_rejection
            - click
            - open
            - initial_open
            - amp_click
            - amp_open
            - amp_initial_open
            - generation_failure
            - generation_rejection
            - list_unsubscribe
            - link_unsubscribe
        timestamp:
          type: string
          description: When the event occurred (ISO 8601)
          example: '2024-01-15T10:31:00.000Z'
        request_id:
          type: string
          description: The transmission/request ID that generated this event
          example: '7610639000055488914'
        rcpt_to:
          type: string
          format: email
          description: Recipient email address
          example: recipient@example.com
        raw_rcpt_to:
          type: string
          format: email
          description: Original recipient email address before any modifications
          example: recipient@example.com
        recipient_domain:
          type: string
          description: Domain of the recipient
          example: example.com
        mailbox_provider:
          type: string
          description: Mailbox provider of the recipient
          example: Gmail
        mailbox_provider_region:
          type: string
          description: Region of the mailbox provider
          example: Global
        message_id:
          type:
            - string
            - 'null'
          description: SMTP message ID
          example: 699715cd9e6961853a97
        subject:
          type:
            - string
            - 'null'
          description: Email subject line
          example: Welcome to Lettr
        friendly_from:
          type:
            - string
            - 'null'
          description: Friendly from address
          example: sender@example.com
        sending_domain:
          type:
            - string
            - 'null'
          description: The sending domain
          example: example.com
        sending_ip:
          type:
            - string
            - 'null'
          description: IP address used to send the email
          example: 168.203.51.91
        click_tracking:
          type:
            - boolean
            - 'null'
          description: Whether click tracking was enabled
        open_tracking:
          type:
            - boolean
            - 'null'
          description: Whether open tracking was enabled
        transactional:
          type:
            - boolean
            - 'null'
          description: Whether this was a transactional message
        msg_size:
          type:
            - integer
            - 'null'
          description: Message size in bytes
          example: 30823
        injection_time:
          type:
            - string
            - 'null'
          description: When the message was injected into the system (ISO 8601)
          example: '2024-01-15T10:30:00.000Z'
        rcpt_meta:
          type:
            - array
            - 'null'
          description: Recipient metadata
        campaign_id:
          type:
            - string
            - 'null'
          description: Campaign identifier
          example: welcome-series
        template_id:
          type:
            - string
            - 'null'
          description: Template identifier
          example: template_7610639000055488914
        template_version:
          type:
            - string
            - 'null'
          description: Template version
          example: '0'
        ip_pool:
          type:
            - string
            - 'null'
          description: IP pool used for sending
          example: default
        msg_from:
          type:
            - string
            - 'null'
          description: Envelope sender (MAIL FROM)
          example: msprvs1=abc123=bounces@sparkpostmail1.com
        rcpt_type:
          type:
            - string
            - 'null'
          description: Recipient type
        rcpt_tags:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Recipient tags
        amp_enabled:
          type:
            - boolean
            - 'null'
          description: Whether AMP was enabled
        delv_method:
          type:
            - string
            - 'null'
          description: Delivery method (e.g. esmtp)
          example: esmtp
        recv_method:
          type:
            - string
            - 'null'
          description: Reception method (e.g. rest)
          example: rest
        routing_domain:
          type:
            - string
            - 'null'
          description: Routing domain
          example: gmail.com
        scheduled_time:
          type:
            - string
            - 'null'
          description: Scheduled delivery time if the email was scheduled
        ab_test_id:
          type:
            - string
            - 'null'
          description: A/B test identifier
        ab_test_version:
          type:
            - string
            - 'null'
          description: A/B test version
    UserAgentParsed:
      type: object
      description: Parsed user agent information from the open/click event.
      properties:
        agent_family:
          type:
            - string
            - 'null'
          description: Browser or email client family
          example: Edge
        device_brand:
          type:
            - string
            - 'null'
          description: Device brand (e.g. Apple, Samsung)
        device_family:
          type:
            - string
            - 'null'
          description: Device family (e.g. iPhone, Desktop)
        os_family:
          type:
            - string
            - 'null'
          description: Operating system family
          example: Windows
        os_version:
          type:
            - string
            - 'null'
          description: Operating system version
          example: '10'
        is_mobile:
          type:
            - boolean
            - 'null'
          description: Whether the device is mobile
        is_proxy:
          type:
            - boolean
            - 'null'
          description: Whether the request came through a proxy
        is_prefetched:
          type:
            - boolean
            - 'null'
          description: >-
            Whether the open was prefetched by an email provider (e.g. Gmail
            Image Proxy, Apple Mail Privacy Protection). If true, this may not
            represent a real human open.
    GeoIp:
      type: object
      description: Geolocation data derived from the IP address of the open/click event.
      properties:
        country:
          type:
            - string
            - 'null'
          description: ISO 3166-1 alpha-2 country code
          example: CZ
        region:
          type:
            - string
            - 'null'
          description: Region or state code
          example: '10'
        city:
          type:
            - string
            - 'null'
          description: City name
          example: Prague
        latitude:
          type:
            - number
            - 'null'
          description: Latitude
          example: 50.0883
        longitude:
          type:
            - number
            - 'null'
          description: Longitude
          example: 14.4124
        zip:
          type:
            - string
            - 'null'
          description: ZIP code
          example: '110'
        postal_code:
          type:
            - string
            - 'null'
          description: Postal code
          example: 110 00
  responses:
    UnauthorizedError:
      description: Unauthorized - Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedResponse'
          examples:
            missing_key:
              summary: Missing API key
              value:
                message: API key is required.
            invalid_key:
              summary: Invalid API key
              value:
                message: Invalid API key.
    ForbiddenError:
      description: Forbidden - API key does not have the required scope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: >-
              Your API key does not have the required permissions for this
              action.
            error_code: insufficient_scope
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key for authentication

````