> ## 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.

# Schedule Email

> Schedule a transactional email for future delivery. Accepts the same payload as `POST /emails` with an additional required `scheduled_at` field. The email must be scheduled at least 5 minutes in the future and within 3 days.

Schedule a transactional email for future delivery. Accepts the same payload as `POST /emails` with an additional required `scheduled_at` field.


## OpenAPI

````yaml POST /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:
    post:
      tags:
        - Emails
      summary: Schedule Email
      description: >-
        Schedule a transactional email for future delivery. Accepts the same
        payload as `POST /emails` with an additional required `scheduled_at`
        field. The email must be scheduled at least 5 minutes in the future and
        within 3 days.
      operationId: scheduleEmail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleEmailRequest'
            example:
              from: sender@example.com
              from_name: Sender Name
              to:
                - recipient@example.com
              subject: Scheduled Newsletter
              html: <h1>Hello</h1><p>This email was scheduled!</p>
              scheduled_at: '2024-01-16T10:00:00Z'
              options:
                click_tracking: true
                open_tracking: true
      responses:
        '201':
          description: >-
            Email scheduled for delivery. Free tier teams receive quota headers
            indicating their usage and limits.
          headers:
            X-Monthly-Limit:
              description: >-
                Total monthly email limit for this team. Only present for free
                tier teams.
              schema:
                type: integer
                example: 3000
            X-Monthly-Remaining:
              description: >-
                Remaining emails allowed this month. Only present for free tier
                teams.
              schema:
                type: integer
                example: 2500
            X-Monthly-Reset:
              description: Unix timestamp when the monthly quota resets.
              schema:
                type: integer
                example: 1740787200
            X-Daily-Limit:
              description: >-
                Total daily email limit for this team. Only present for free
                tier teams.
              schema:
                type: integer
                example: 100
            X-Daily-Remaining:
              description: >-
                Remaining emails allowed today. Only present for free tier
                teams.
              schema:
                type: integer
                example: 75
            X-Daily-Reset:
              description: Unix timestamp when the daily quota resets.
              schema:
                type: integer
                example: 1739600000
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendEmailSuccessResponse'
              example:
                message: Email scheduled for delivery.
                data:
                  request_id: '12345678901234567890'
                  accepted: 1
                  rejected: 0
        '400':
          description: Failed to schedule email (domain errors)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_domain:
                  summary: Invalid sender domain
                  value:
                    message: >-
                      The sender domain could not be determined from the email
                      address.
                    error_code: invalid_domain
                unconfigured_domain:
                  summary: Unconfigured sender domain
                  value:
                    message: >-
                      The sender domain is not configured or approved for
                      sending.
                    error_code: unconfigured_domain
        '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:
                  scheduled_at:
                    - The scheduled delivery time is required.
        '429':
          description: Sending quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Sending quota exceeded. Upgrade your plan to continue sending.
                error_code: quota_exceeded
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          description: Email transmission failed (upstream provider error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Unconfigured Sending Domain <sender.example.com>
                error_code: transmission_failed
      security:
        - bearerAuth: []
components:
  schemas:
    ScheduleEmailRequest:
      type: object
      description: >-
        Schedule email request. Extends the standard send email request with a
        required `scheduled_at` field.
      allOf:
        - $ref: '#/components/schemas/SendEmailRequest'
        - type: object
          required:
            - scheduled_at
          properties:
            scheduled_at:
              type: string
              format: date-time
              description: >-
                The UTC date/time when the email should be sent. Must be at
                least 5 minutes in the future and within 3 days.
              example: '2024-01-16T10:00:00Z'
    SendEmailSuccessResponse:
      type: object
      required:
        - message
        - data
      properties:
        message:
          type: string
          description: Human-readable success message
          example: Email queued for delivery.
        data:
          type: object
          required:
            - request_id
            - accepted
            - rejected
          properties:
            request_id:
              type: string
              description: Unique identifier for this email transmission
              example: '12345678901234567890'
            accepted:
              type: integer
              minimum: 0
              description: Number of recipients accepted for delivery
              example: 1
            rejected:
              type: integer
              minimum: 0
              description: Number of recipients rejected
              example: 0
    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'
    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.
    SendEmailRequest:
      type: object
      description: >-
        Email sending request. **Required:** `from`, `to`, and at least one of
        `html`, `text`, or `template_slug`. The `subject` is required unless
        `template_slug` is provided — when using a template, the subject
        defaults to the template's subject (or template name as fallback), but
        can be overridden. When using `template_slug`, if `project_id` is not
        provided, the team's default project will be used.
      required:
        - from
        - to
      properties:
        from:
          type: string
          format: email
          maxLength: 255
          description: Sender email address
          example: sender@example.com
        from_name:
          type:
            - string
            - 'null'
          maxLength: 255
          description: Sender display name
          example: Sender Name
        subject:
          type:
            - string
            - 'null'
          maxLength: 998
          description: >-
            Email subject line. Required when not using a template. When using
            `template_slug`, defaults to the template's subject (or template
            name as fallback). If provided alongside a template, overrides the
            template subject.
          example: Welcome to Lettr
        to:
          type: array
          description: Recipient email addresses
          minItems: 1
          maxItems: 50
          items:
            type: string
            format: email
            maxLength: 255
          example:
            - recipient@example.com
        cc:
          type: array
          description: Carbon copy recipient email addresses
          items:
            type: string
            format: email
            maxLength: 255
          example:
            - cc@example.com
        bcc:
          type: array
          description: Blind carbon copy recipient email addresses
          items:
            type: string
            format: email
            maxLength: 255
          example:
            - bcc@example.com
        reply_to:
          type:
            - string
            - 'null'
          format: email
          maxLength: 255
          description: Reply-To email address
          example: reply@example.com
        reply_to_name:
          type:
            - string
            - 'null'
          maxLength: 255
          description: Reply-To display name
          example: Reply Name
        html:
          type:
            - string
            - 'null'
          description: >-
            HTML content of the email. At least one of `html` or `text` is
            required, but providing both is recommended for best compatibility
            across email clients.
          example: <h1>Hello</h1><p>Welcome!</p>
        text:
          type:
            - string
            - 'null'
          description: >-
            Plain text content of the email. At least one of `html` or `text` is
            required, but providing both is recommended for best compatibility
            across email clients.
          example: |-
            Hello

            Welcome!
        amp_html:
          type:
            - string
            - 'null'
          description: AMP HTML content for supported email clients
        project_id:
          type:
            - integer
            - 'null'
          description: >-
            Project ID containing the template. If not provided when using
            template_slug, the team's default project will be used.
          example: 123
        template_slug:
          type:
            - string
            - 'null'
          maxLength: 255
          description: >-
            Template slug to use for email content. When provided, the
            template's HTML will be used instead of the html field.
          example: welcome-email
        template_version:
          type:
            - integer
            - 'null'
          minimum: 1
          description: >-
            Specific template version to use. If not provided, the active
            version will be used.
          example: 1
        tag:
          type: string
          maxLength: 64
          description: >-
            Tag for tracking and analytics. Automatically set from template_slug
            if not provided.
          example: welcome-series-2024
        metadata:
          type: object
          description: Custom metadata attached to the email for tracking purposes
          additionalProperties:
            type: string
          example:
            user_id: '12345'
            campaign: onboarding
        headers:
          type: object
          description: >-
            Custom email headers. Up to 10 headers allowed. Standard envelope
            headers (From, To, Subject, etc.), SparkPost internal headers
            (X-MSYS-API), and List-Unsubscribe and List-Unsubscribe-Post headers
            are managed by the system and cannot be set manually.
          maxProperties: 10
          additionalProperties:
            type: string
            maxLength: 998
          example:
            X-Mailer: MyApp/1.0
            X-Custom-ID: abc-123
        substitution_data:
          type: object
          description: Variables for template substitution in email content
          additionalProperties:
            type: string
          example:
            first_name: John
            company: Acme Inc
        options:
          type: object
          description: Email delivery options
          properties:
            click_tracking:
              type: boolean
              description: Enable click tracking for links in the email
            open_tracking:
              type: boolean
              description: Enable open tracking via tracking pixel
            transactional:
              type: boolean
              description: Mark email as transactional (not marketing)
            inline_css:
              type: boolean
              description: Inline CSS styles in HTML content
            perform_substitutions:
              type: boolean
              description: Perform variable substitutions in content
        attachments:
          type: array
          description: >-
            File attachments. When provided, each attachment must include name,
            type, and data.
          items:
            $ref: '#/components/schemas/Attachment'
    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 | Could not cancel the
        scheduled transmission (already sent or upstream error). |

        | `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
        - 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
    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.
    Attachment:
      type: object
      description: Email attachment
      required:
        - name
        - type
        - data
      properties:
        name:
          type: string
          maxLength: 255
          description: Filename of the attachment
          example: invoice.pdf
        type:
          type: string
          maxLength: 255
          description: MIME type of the attachment
          example: application/pdf
        data:
          type: string
          pattern: ^[A-Za-z0-9+/=]+$
          description: Base64 encoded file content (no line breaks)
          example: JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL1BhZ2U=
  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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key for authentication

````