> ## 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. # Get Scheduled Email > Retrieve a scheduled email by the `request_id` returned when it was scheduled (`sch_...`). **Breaking change.** Scheduled emails are no longer parked inside SparkPost with `options.start_time`, because SparkPost retired its per-transmission GET endpoint. Lettr now answers from its own store, so the response is correct the instant the email is scheduled and a cancelled email can be told apart from one that never existed. `request_id` is Lettr's own `sch_...` id, SparkPost's id is the separate `transmission_id` field (`null` until the email is injected, and the value that appears as `transmission_id` on your webhook events), and `state` is one of `scheduled`, `sending`, `sent`, `cancelled` or `failed`. For emails scheduled **before** this change there is no Lettr record, only the SparkPost transmission id you stored. Those ids are still accepted and fall back to a delivery-events lookup, which returns the **old** response shape (`ShowScheduledTransmissionResponse`, with SparkPost's pass-through `state` values and no `request_id`). A sandbox key only sees the emails it scheduled itself. ## OpenAPI ````yaml GET /emails/scheduled/{transmissionId} 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/{transmissionId}: get: tags: - Emails summary: Get Scheduled Email description: >- Retrieve a scheduled email by the `request_id` returned when it was scheduled (`sch_...`). **Breaking change.** Scheduled emails are no longer parked inside SparkPost with `options.start_time`, because SparkPost retired its per-transmission GET endpoint. Lettr now answers from its own store, so the response is correct the instant the email is scheduled and a cancelled email can be told apart from one that never existed. `request_id` is Lettr's own `sch_...` id, SparkPost's id is the separate `transmission_id` field (`null` until the email is injected, and the value that appears as `transmission_id` on your webhook events), and `state` is one of `scheduled`, `sending`, `sent`, `cancelled` or `failed`. For emails scheduled **before** this change there is no Lettr record, only the SparkPost transmission id you stored. Those ids are still accepted and fall back to a delivery-events lookup, which returns the **old** response shape (`ShowScheduledTransmissionResponse`, with SparkPost's pass-through `state` values and no `request_id`). A sandbox key only sees the emails it scheduled itself. operationId: showScheduledEmail parameters: - name: transmissionId in: path required: true description: >- The `request_id` returned when the email was scheduled (`sch_...`). A bare SparkPost transmission id is also accepted, for emails scheduled before Lettr owned the schedule; those return the legacy response shape. schema: type: string example: sch_01JQZ3N2K8XW9V6M4TBRC7YHDE responses: '200': description: >- Scheduled transmission retrieved successfully. Returns the scheduled email when Lettr knows the id, or the legacy events-derived shape for a SparkPost transmission id from before this change. content: application/json: schema: oneOf: - type: object description: Returned for a `sch_...` id that Lettr knows about. required: - message - data properties: message: type: string example: Scheduled transmission retrieved successfully. data: $ref: '#/components/schemas/ScheduledEmailResponse' - $ref: '#/components/schemas/ShowScheduledTransmissionResponse' examples: scheduled: summary: Waiting for its delivery time value: message: Scheduled transmission retrieved successfully. data: 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: [] sent: summary: Injected into SparkPost (delivery events populated) value: message: Scheduled transmission retrieved successfully. data: request_id: sch_01JQZ3N2K8XW9V6M4TBRC7YHDE transmission_id: '12345678901234567890' state: sent 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: - event_id: evt-delivery-1 type: delivery timestamp: '2024-01-16T10:00:02.000Z' request_id: '12345678901234567890' rcpt_to: recipient@example.com raw_rcpt_to: recipient@example.com recipient_domain: example.com mailbox_provider: Gmail mailbox_provider_region: Global subject: Scheduled Newsletter friendly_from: sender@example.com queue_time: 500 cancelled: summary: Cancelled before injection value: message: Scheduled transmission retrieved successfully. data: request_id: sch_01JQZ3N2K8XW9V6M4TBRC7YHDE transmission_id: null state: cancelled 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: [] legacy: summary: >- Legacy SparkPost transmission id (old response shape, from delivery events) value: message: Scheduled transmission retrieved successfully. data: transmission_id: '12345678901234567890' state: delivered scheduled_at: null from: sender@example.com from_name: null subject: Scheduled Newsletter recipients: - recipient@example.com num_recipients: 1 events: - event_id: evt-delivery-1 type: delivery timestamp: '2024-01-16T10:00:02.000Z' request_id: '12345678901234567890' rcpt_to: recipient@example.com raw_rcpt_to: recipient@example.com recipient_domain: example.com mailbox_provider: Gmail mailbox_provider_region: Global subject: Scheduled Newsletter friendly_from: sender@example.com queue_time: 500 - event_id: evt-injection-1 type: injection timestamp: '2024-01-16T10:00:00.000Z' request_id: '12345678901234567890' rcpt_to: recipient@example.com raw_rcpt_to: recipient@example.com recipient_domain: example.com mailbox_provider: Gmail mailbox_provider_region: Global subject: Scheduled Newsletter friendly_from: sender@example.com '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': description: Scheduled transmission not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Scheduled transmission not found. error_code: not_found '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServiceUnavailableError' security: - bearerAuth: [] components: schemas: 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' ShowScheduledTransmissionResponse: type: object required: - message - data properties: message: type: string example: Scheduled transmission retrieved successfully. data: type: object required: - transmission_id - state - from - subject - recipients - num_recipients - events properties: transmission_id: type: string description: The unique transmission ID. example: '12345678901234567890' state: type: string description: >- Current state of the transmission. `submitted`/`generating` — still pending in SparkPost. `scheduled` — injected but not yet delivered (has `injection` event only). `delivered` — successfully delivered. `bounced` — rejected by recipient server. `failed` — generation or policy failure. enum: - submitted - generating - scheduled - delivered - bounced - failed - unknown example: submitted scheduled_at: type: - string - 'null' format: date-time description: >- The scheduled delivery time in ISO 8601 format. Present when the transmission is still pending. May be `null` when the transmission has already been delivered. example: '2024-01-16T10:00:00+00:00' 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 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 description: Total number of recipients. example: 1 events: type: array description: >- Delivery events for this transmission. Empty array when the email is still scheduled. Populated with delivery, bounce, open, click, and other events once the email has been processed. items: $ref: '#/components/schemas/EmailEvent' 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' 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: '#/components/schemas/InjectionEvent' delivery: '#/components/schemas/DeliveryEvent' bounce: '#/components/schemas/BounceEvent' delay: '#/components/schemas/DelayEvent' out_of_band: '#/components/schemas/OutOfBandEvent' spam_complaint: '#/components/schemas/SpamComplaintEvent' policy_rejection: '#/components/schemas/PolicyRejectionEvent' click: '#/components/schemas/ClickEvent' open: '#/components/schemas/OpenEvent' initial_open: '#/components/schemas/InitialOpenEvent' amp_click: '#/components/schemas/AmpClickEvent' amp_open: '#/components/schemas/AmpOpenEvent' amp_initial_open: '#/components/schemas/AmpInitialOpenEvent' generation_failure: '#/components/schemas/GenerationFailureEvent' generation_rejection: '#/components/schemas/GenerationRejectionEvent' list_unsubscribe: '#/components/schemas/ListUnsubscribeEvent' link_unsubscribe: '#/components/schemas/LinkUnsubscribeEvent' 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 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 ServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: An unexpected error occurred. Please try again later. error_code: send_error ServiceUnavailableError: description: >- Service unavailable - the API key could not be verified, so the request was not processed. This does not mean the key is invalid; retry after the delay given in the Retry-After header. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 5 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Unable to verify your API key right now. Please retry shortly. error_code: auth_unavailable securitySchemes: bearerAuth: type: http scheme: bearer description: API key for authentication ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.