openapi.json

{
  "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"
    }
  },
  "servers": [
    {
      "url": "https://app.lettr.com/api",
      "description": "Production"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "healthCheck",
        "summary": "Health Check",
        "description": "Check the health status of the API. This endpoint does not require authentication.",
        "tags": ["System"],
        "security": [],
        "responses": {
          "200": {
            "description": "API is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["message", "data"],
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Health check passed."
                    },
                    "data": {
                      "type": "object",
                      "required": ["status", "timestamp"],
                      "properties": {
                        "status": {
                          "type": "string",
                          "example": "ok"
                        },
                        "timestamp": {
                          "type": "string",
                          "format": "date-time",
                          "example": "2024-01-15T10:30:00.000Z"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "message": "Health check passed.",
                  "data": {
                    "status": "ok",
                    "timestamp": "2024-01-15T10:30:00.000Z"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/auth/check": {
      "get": {
        "operationId": "authCheck",
        "summary": "Validate API Key",
        "description": "Validate the provided API key and return associated team information. Use this endpoint to verify API key validity in client libraries.",
        "tags": ["System"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "API key is valid",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["message", "data"],
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "API key is valid."
                    },
                    "data": {
                      "type": "object",
                      "required": ["team_id", "timestamp"],
                      "properties": {
                        "team_id": {
                          "type": "integer",
                          "description": "The team ID associated with the API key",
                          "example": 123
                        },
                        "timestamp": {
                          "type": "string",
                          "format": "date-time",
                          "example": "2024-01-15T10:30:00.000Z"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "message": "API key is valid.",
                  "data": {
                    "team_id": 123,
                    "timestamp": "2024-01-15T10:30:00.000Z"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/emails": {
      "post": {
        "operationId": "sendEmail",
        "summary": "Send Email",
        "description": "Send a transactional email with optional attachments, tracking, and personalization. At least one of `html` or `text` content must be provided.",
        "tags": ["Emails"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendEmailRequest"
              },
              "examples": {
                "minimal": {
                  "summary": "Minimal request (required fields only)",
                  "description": "The absolute minimum required to send an email: from, to, subject, and either html or text content. Subject is required when not using a template.",
                  "value": {
                    "from": "sender@example.com",
                    "to": ["recipient@example.com"],
                    "subject": "Hello",
                    "html": "<p>Hello!</p>"
                  }
                },
                "html-and-text": {
                  "summary": "HTML and plain text (recommended)",
                  "description": "Sending both HTML and plain text ensures email renders correctly in all email clients.",
                  "value": {
                    "from": "sender@example.com",
                    "from_name": "Sender Name",
                    "to": ["recipient@example.com"],
                    "subject": "Welcome to Lettr",
                    "html": "<h1>Hello</h1><p>Welcome to our service!</p>",
                    "text": "Hello\n\nWelcome to our service!",
                    "options": {
                      "click_tracking": true,
                      "open_tracking": true
                    }
                  }
                },
                "html-only": {
                  "summary": "HTML only",
                  "description": "Send HTML content only. Some email clients may not render properly without a text fallback.",
                  "value": {
                    "from": "sender@example.com",
                    "to": ["recipient@example.com"],
                    "subject": "Welcome to Lettr",
                    "html": "<h1>Hello</h1><p>Welcome to our service!</p>"
                  }
                },
                "text-only": {
                  "summary": "Plain text only",
                  "description": "Send plain text content only. Ideal for simple notifications.",
                  "value": {
                    "from": "sender@example.com",
                    "to": ["recipient@example.com"],
                    "subject": "Order Confirmation",
                    "text": "Your order #12345 has been confirmed.\n\nThank you for your purchase!"
                  }
                },
                "with-attachments": {
                  "summary": "Email with attachments",
                  "description": "Send an email with file attachments. Attachments must be base64 encoded.",
                  "value": {
                    "from": "billing@example.com",
                    "from_name": "Billing Department",
                    "to": ["customer@example.com"],
                    "subject": "Your Invoice",
                    "html": "<p>Please find your invoice attached.</p>",
                    "text": "Please find your invoice attached.",
                    "attachments": [
                      {
                        "name": "invoice.pdf",
                        "type": "application/pdf",
                        "data": "JVBERi0xLjQKJeLjz9M..."
                      }
                    ]
                  }
                },
                "with-personalization": {
                  "summary": "Personalized email with substitution",
                  "description": "Use substitution_data to personalize email content with dynamic variables.",
                  "value": {
                    "from": "hello@example.com",
                    "from_name": "Acme Inc",
                    "to": ["john@example.com"],
                    "subject": "Welcome, {{first_name}}!",
                    "html": "<h1>Hello {{first_name}}</h1><p>Welcome to {{company}}!</p>",
                    "text": "Hello {{first_name}},\n\nWelcome to {{company}}!",
                    "substitution_data": {
                      "first_name": "John",
                      "company": "Acme Inc"
                    },
                    "metadata": {
                      "user_id": "12345",
                      "campaign": "onboarding"
                    }
                  }
                },
                "with-template": {
                  "summary": "Email using a template",
                  "description": "Send an email using a pre-defined template. The template's HTML content and subject will be used. You can optionally override the subject.",
                  "value": {
                    "from": "hello@example.com",
                    "to": ["john@example.com"],
                    "template_slug": "welcome-email",
                    "substitution_data": {
                      "first_name": "John"
                    }
                  }
                },
                "with-template-and-project": {
                  "summary": "Email using a template from a specific project",
                  "description": "Send an email using a template from a specific project with a specific version. Subject is taken from the template unless explicitly provided.",
                  "value": {
                    "from": "hello@example.com",
                    "to": ["john@example.com"],
                    "project_id": 123,
                    "template_slug": "welcome-email",
                    "template_version": 2,
                    "substitution_data": {
                      "first_name": "John"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email queued 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 (start of next month). Only present for free tier teams.",
                "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 (tomorrow midnight UTC). Only present for free tier teams.",
                "schema": {
                  "type": "integer",
                  "example": 1739600000
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendEmailSuccessResponse"
                },
                "example": {
                  "message": "Email queued for delivery.",
                  "data": {
                    "request_id": "12345678901234567890",
                    "accepted": 1,
                    "rejected": 0
                  }
                }
              }
            }
          },
          "400": {
            "description": "Failed to send 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"
          },
          "404": {
            "description": "Template or project not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "template_not_found": {
                    "summary": "Template not found",
                    "value": {
                      "message": "Template with slug 'welcome-email' was not found.",
                      "error_code": "template_not_found"
                    }
                  },
                  "project_not_found": {
                    "summary": "Project not found",
                    "value": {
                      "message": "Project with ID '123' was not found or you don't have access to it.",
                      "error_code": "template_not_found"
                    }
                  },
                  "no_default_project": {
                    "summary": "No default project configured",
                    "value": {
                      "message": "No default project is configured for this team.",
                      "error_code": "template_not_found"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                },
                "example": {
                  "message": "Validation failed.",
                  "error_code": "validation_error",
                  "errors": {
                    "from": ["The sender email address is required."],
                    "to": ["At least one recipient email address is required."]
                  }
                }
              }
            }
          },
          "429": {
            "description": "Sending quota exceeded. The response includes quota headers to help determine current usage and when the limit resets.",
            "headers": {
              "X-Monthly-Limit": {
                "description": "Total monthly email limit for this team.",
                "schema": {
                  "type": "integer",
                  "example": 3000
                }
              },
              "X-Monthly-Remaining": {
                "description": "Remaining emails allowed this month (0 when limit is hit).",
                "schema": {
                  "type": "integer",
                  "example": 0
                }
              },
              "X-Monthly-Reset": {
                "description": "Unix timestamp when the monthly quota resets (start of next month).",
                "schema": {
                  "type": "integer",
                  "example": 1740787200
                }
              },
              "X-Daily-Limit": {
                "description": "Total daily email limit for this team.",
                "schema": {
                  "type": "integer",
                  "example": 100
                }
              },
              "X-Daily-Remaining": {
                "description": "Remaining emails allowed today (0 when limit is hit).",
                "schema": {
                  "type": "integer",
                  "example": 0
                }
              },
              "X-Daily-Reset": {
                "description": "Unix timestamp when the daily quota resets (tomorrow midnight UTC).",
                "schema": {
                  "type": "integer",
                  "example": 1739600000
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "monthly_quota_exceeded": {
                    "summary": "Monthly sending quota exceeded",
                    "value": {
                      "message": "Sending quota exceeded. Upgrade your plan to continue sending.",
                      "error_code": "quota_exceeded"
                    }
                  },
                  "daily_quota_exceeded": {
                    "summary": "Daily sending quota exceeded",
                    "value": {
                      "message": "Daily sending quota exceeded. Please try again tomorrow.",
                      "error_code": "daily_quota_exceeded"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Failed to send email. Please try again later.",
                  "error_code": "send_error"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      }
    },
    "/emails/events": {
      "get": {
        "operationId": "listEmailEvents",
        "summary": "List Email Events",
        "description": "Retrieve email events (deliveries, bounces, opens, clicks, etc.) for your account. Events are returned in reverse chronological order. If no `from` date is provided, defaults to the last 10 days.",
        "tags": ["Emails"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "events",
            "in": "query",
            "required": false,
            "description": "Comma-separated list of event types to filter by. Valid types: `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`.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "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"]
              }
            },
            "style": "form",
            "explode": false,
            "examples": {
              "single": {
                "summary": "Single event type",
                "value": ["delivery"]
              },
              "multiple": {
                "summary": "Multiple event types",
                "value": ["delivery", "bounce", "open"]
              }
            }
          },
          {
            "name": "recipients",
            "in": "query",
            "required": false,
            "description": "Comma-separated list of recipient email addresses to filter by.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "email"
              }
            },
            "style": "form",
            "explode": false,
            "examples": {
              "single": {
                "summary": "Single recipient",
                "value": ["recipient@example.com"]
              },
              "multiple": {
                "summary": "Multiple recipients",
                "value": ["recipient@example.com", "other@example.com"]
              }
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Start date for the event search range. Defaults to 10 days ago if not provided.",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2024-01-01"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "End date for the event search range. Defaults to now if not provided.",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2024-01-31"
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "Number of events per page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "example": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Pagination cursor returned from a previous request.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "transmissions",
            "in": "query",
            "required": false,
            "description": "Filter events by transmission ID (request_id).",
            "schema": {
              "type": "string",
              "example": "12345678901234567890"
            }
          },
          {
            "name": "bounce_classes",
            "in": "query",
            "required": false,
            "description": "Comma-separated list of bounce classification codes to filter by.",
            "schema": {
              "type": "string",
              "example": "10,30"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Email events retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListEmailEventsResponse"
                },
                "example": {
                  "message": "Email events retrieved successfully.",
                  "data": {
                    "events": {
                      "data": [
                        {
                          "event_id": "event-delivery-1",
                          "type": "delivery",
                          "timestamp": "2024-01-15T10:31:00.000Z",
                          "request_id": "12345678901234567890",
                          "rcpt_to": "recipient@example.com",
                          "subject": "Welcome to Lettr",
                          "friendly_from": "sender@example.com",
                          "queue_time": 500
                        },
                        {
                          "event_id": "event-bounce-1",
                          "type": "bounce",
                          "timestamp": "2024-01-15T10:32:00.000Z",
                          "request_id": "12345678901234567891",
                          "rcpt_to": "bounced@example.com",
                          "subject": "Welcome to Lettr",
                          "bounce_class": 10,
                          "error_code": "550",
                          "reason": "User unknown"
                        }
                      ],
                      "total_count": 2,
                      "from": "2024-01-05T00:00:00+00:00",
                      "to": "2024-01-15T10:35:00+00:00",
                      "pagination": {
                        "next_cursor": null,
                        "per_page": 25
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "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 be an integer."]
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/emails/{requestId}": {
      "get": {
        "operationId": "getEmailDetail",
        "summary": "Get Email Detail",
        "description": "Retrieve all events for a specific sent email by its request ID. Returns delivery, bounce, open, click, and other events in reverse chronological order. If no `from` date is provided, defaults to the last 10 days.",
        "tags": ["Emails"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "description": "The request ID (transmission ID) of the sent email.",
            "schema": {
              "type": "string",
              "example": "7610639000055488914"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Start date for the event search range. Defaults to 10 days ago if not provided.",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2024-01-01"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "End date for the event search range. Defaults to now if not provided.",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2024-01-31"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Email detail retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetEmailDetailResponse"
                },
                "example": {
                  "message": "Email retrieved successfully.",
                  "data": {
                    "events": {
                      "data": [
                        {
                          "event_id": "event-open-1",
                          "type": "open",
                          "timestamp": "2024-01-15T10:32:00.000Z",
                          "request_id": "7610639000055488914",
                          "rcpt_to": "recipient@example.com",
                          "subject": "Welcome to Lettr",
                          "friendly_from": "sender@example.com"
                        },
                        {
                          "event_id": "event-delivery-1",
                          "type": "delivery",
                          "timestamp": "2024-01-15T10:31:00.000Z",
                          "request_id": "7610639000055488914",
                          "rcpt_to": "recipient@example.com",
                          "subject": "Welcome to Lettr",
                          "friendly_from": "sender@example.com",
                          "queue_time": 500
                        },
                        {
                          "event_id": "event-injection-1",
                          "type": "injection",
                          "timestamp": "2024-01-15T10:30:00.000Z",
                          "request_id": "7610639000055488914",
                          "rcpt_to": "recipient@example.com",
                          "subject": "Welcome to Lettr",
                          "friendly_from": "sender@example.com"
                        }
                      ],
                      "total_count": 3,
                      "from": "2024-01-05T00:00:00+00:00",
                      "to": "2024-01-15T10:35:00+00:00"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "description": "Email not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Email not found.",
                  "error_code": "not_found"
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                },
                "example": {
                  "message": "Validation failed.",
                  "error_code": "validation_error",
                  "errors": {
                    "from": ["The from parameter must be a valid date."]
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/emails/scheduled": {
      "post": {
        "operationId": "scheduleEmail",
        "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.",
        "tags": ["Emails"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "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"
                }
              }
            }
          }
        }
      }
    },
    "/emails/scheduled/{transmissionId}": {
      "get": {
        "operationId": "showScheduledEmail",
        "summary": "Get Scheduled Email",
        "description": "Retrieve details of a scheduled email transmission by its transmission ID. If the transmission is still pending, returns the scheduled state. If the transmission has already been processed by SparkPost, automatically falls back to returning delivery events with the same response shape.",
        "tags": ["Emails"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "transmissionId",
            "in": "path",
            "required": true,
            "description": "The transmission ID returned when the email was scheduled.",
            "schema": {
              "type": "string",
              "example": "12345678901234567890"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Scheduled transmission retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShowScheduledTransmissionResponse"
                },

                "examples": {
                  "pending": {
                    "summary": "Still scheduled (pending delivery)",
                    "value": {
                      "message": "Scheduled transmission retrieved successfully.",
                      "data": {
                        "transmission_id": "12345678901234567890",
                        "state": "submitted",
                        "scheduled_at": "2024-01-16T10:00:00+00:00",
                        "from": "sender@example.com",
                        "from_name": "Sender Name",
                        "subject": "Scheduled Newsletter",
                        "recipients": ["recipient@example.com"],
                        "num_recipients": 1,
                        "events": []
                      }
                    }
                  },
                  "delivered": {
                    "summary": "Already processed (delivery events returned)",
                    "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",
                            "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",
                            "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"
          }
        }
      },
      "delete": {
        "operationId": "cancelScheduledEmail",
        "summary": "Cancel Scheduled Email",
        "description": "Cancel a scheduled email transmission before it is sent. Once the scheduled delivery time has passed, the transmission can no longer be cancelled.",
        "tags": ["Emails"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "transmissionId",
            "in": "path",
            "required": true,
            "description": "The transmission ID returned when the email was scheduled.",
            "schema": {
              "type": "string",
              "example": "12345678901234567890"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Scheduled transmission cancelled successfully",
            "content": {
              "application/json": {
                "example": {
                  "message": "Scheduled transmission cancelled successfully."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenError"
          },
          "409": {
            "description": "Cancellation failed (transmission already sent or not found)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Failed to cancel scheduled transmission trans-123.",
                  "error_code": "schedule_cancellation_failed"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/domains": {
      "get": {
        "operationId": "listDomains",
        "summary": "List Domains",
        "description": "Retrieve all sending domains registered with your account. Returns domains with their current status, verification state, and timestamps.",
        "tags": ["Domains"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of domains retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListDomainsResponse"
                },
                "example": {
                  "message": "Domains retrieved successfully.",
                  "data": {
                    "domains": [
                      {
                        "domain": "example.com",
                        "status": "approved",
                        "status_label": "Approved",
                        "can_send": true,
                        "cname_status": "valid",
                        "dkim_status": "valid",
                        "created_at": "2024-01-15T10:30:00+00:00",
                        "updated_at": "2024-01-16T14:45:00+00:00"
                      },
                      {
                        "domain": "pending.example.com",
                        "status": "pending",
                        "status_label": "Pending Review",
                        "can_send": false,
                        "cname_status": null,
                        "dkim_status": null,
                        "created_at": "2024-01-17T09:00:00+00:00",
                        "updated_at": "2024-01-17T09:00:00+00:00"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "500": {
            "description": "Server error - Failed to retrieve domains",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Failed to retrieve domains. Please try again later.",
                  "error_code": "send_error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createDomain",
        "summary": "Create Domain",
        "description": "Register a new sending domain with your account. The domain will be created with SparkPost and stored as approved by default, unless global domain reputation marks it for review or blacklist.",
        "tags": ["Domains"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StoreDomainRequest"
              },
              "example": {
                "domain": "example.com"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Domain created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoreDomainResponse"
                },
                "example": {
                  "message": "Domain created successfully.",
                  "data": {
                    "domain": "example.com",
                    "status": "approved",
                    "status_label": "Approved",
                    "dkim": {
                      "public": "MIGfMA0GCSqGSIb3DQEBA...",
                      "selector": "scph0123",
                      "headers": "from:to:subject:date"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "409": {
            "description": "Conflict - Domain already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "This domain is already registered.",
                  "error_code": "resource_already_exists"
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                },
                "example": {
                  "message": "Validation failed.",
                  "error_code": "validation_error",
                  "errors": {
                    "domain": ["The domain must be a valid domain name (e.g., example.com)."]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error - Failed to create domain",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "We could not register your domain. Please try again later.",
                  "error_code": "send_error"
                }
              }
            }
          }
        }
      }
    },
    "/domains/{domain}": {
      "get": {
        "operationId": "showDomain",
        "summary": "Get Domain",
        "description": "Retrieve details of a single sending domain including DNS records and tracking domain configuration.",
        "tags": ["Domains"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "path",
            "required": true,
            "description": "The domain name to retrieve",
            "schema": {
              "type": "string",
              "example": "example.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Domain retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShowDomainResponse"
                },
                "example": {
                  "message": "Domain retrieved successfully.",
                  "data": {
                    "domain": "example.com",
                    "status": "approved",
                    "status_label": "Approved",
                    "can_send": true,
                    "cname_status": "valid",
                    "dkim_status": "valid",
                    "tracking_domain": "tracking.example.com",
                    "dns": {
                      "dkim": {
                        "selector": "scph0123",
                        "public": "MIGfMA0GCSqGSIb3DQEBA..."
                      }
                    },
                    "created_at": "2024-01-15T10:30:00+00:00",
                    "updated_at": "2024-01-16T14:45:00+00:00"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "description": "Domain not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Domain not found.",
                  "error_code": "not_found"
                }
              }
            }
          },
          "500": {
            "description": "Server error - Failed to retrieve domain",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Failed to retrieve domain. Please try again later.",
                  "error_code": "send_error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteDomain",
        "summary": "Delete Domain",
        "description": "Delete a sending domain. This removes the domain from both SparkPost and the Lettr system. The domain will no longer be available for sending emails.",
        "tags": ["Domains"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "path",
            "required": true,
            "description": "The domain name to delete",
            "schema": {
              "type": "string",
              "example": "example.com"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Domain deleted successfully"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "description": "Domain not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Domain not found.",
                  "error_code": "not_found"
                }
              }
            }
          },
          "422": {
            "description": "Validation error - Invalid domain format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                },
                "example": {
                  "message": "Validation failed.",
                  "error_code": "validation_error",
                  "errors": {
                    "domain": ["The domain must be a valid domain name (e.g., example.com)."]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error - Failed to delete domain",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Failed to delete domain. Please try again later.",
                  "error_code": "send_error"
                }
              }
            }
          }
        }
      }
    },
    "/webhooks": {
      "get": {
        "operationId": "listWebhooks",
        "summary": "List Webhooks",
        "description": "Retrieve all webhooks configured for your account. Returns webhooks with their current status, event types, and delivery information.",
        "tags": ["Webhooks"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of webhooks retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListWebhooksResponse"
                },
                "example": {
                  "message": "Webhooks retrieved successfully.",
                  "data": {
                    "webhooks": [
                      {
                        "id": "webhook-abc123",
                        "name": "Order Notifications",
                        "url": "https://example.com/webhook",
                        "enabled": true,
                        "event_types": ["message.delivery", "message.bounce"],
                        "auth_type": "basic",
                        "has_auth_credentials": true,
                        "last_successful_at": "2024-01-15T10:30:00+00:00",
                        "last_failure_at": null,
                        "last_status": "success"
                      },
                      {
                        "id": "webhook-def456",
                        "name": "Support Notifications",
                        "url": "https://example.com/support-webhook",
                        "enabled": false,
                        "event_types": null,
                        "auth_type": "none",
                        "has_auth_credentials": false,
                        "last_successful_at": null,
                        "last_failure_at": "2024-01-14T08:00:00+00:00",
                        "last_status": "failure"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "500": {
            "description": "Server error - Failed to retrieve webhooks",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Failed to retrieve webhooks. Please try again later.",
                  "error_code": "send_error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "storeWebhook",
        "summary": "Create Webhook",
        "description": "Create a new webhook to receive event notifications at the specified URL.",
        "tags": ["Webhooks"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StoreWebhookRequest"
              },
              "example": {
                "name": "Order Notifications",
                "url": "https://example.com/webhook",
                "auth_type": "basic",
                "auth_username": "user",
                "auth_password": "secret",
                "events_mode": "selected",
                "events": ["delivery", "bounce"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoreWebhookResponse"
                },
                "example": {
                  "message": "Webhook created successfully.",
                  "data": {
                    "id": "webhook-abc123",
                    "name": "Order Notifications",
                    "url": "https://example.com/webhook",
                    "enabled": true,
                    "event_types": ["message.delivery", "message.bounce"],
                    "auth_type": "basic",
                    "has_auth_credentials": true,
                    "last_successful_at": null,
                    "last_failure_at": null,
                    "last_status": null
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - SparkPost rejected the webhook configuration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Invalid webhook configuration.",
                  "error_code": "send_error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "409": {
            "description": "Conflict - A webhook with this target URL already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "A webhook with this target URL already exists.",
                  "error_code": "resource_already_exists"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "500": {
            "description": "Server error - Failed to create webhook",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Failed to create webhook. Please try again later.",
                  "error_code": "send_error"
                }
              }
            }
          }
        }
      }
    },
    "/webhooks/{webhookId}": {
      "get": {
        "operationId": "showWebhook",
        "summary": "Get Webhook",
        "description": "Retrieve details of a single webhook including its status, event types, and delivery information.",
        "tags": ["Webhooks"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "webhookId",
            "in": "path",
            "required": true,
            "description": "The webhook ID to retrieve",
            "schema": {
              "type": "string",
              "example": "webhook-abc123"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShowWebhookResponse"
                },
                "example": {
                  "message": "Webhook retrieved successfully.",
                  "data": {
                    "id": "webhook-abc123",
                    "name": "Order Notifications",
                    "url": "https://example.com/webhook",
                    "enabled": true,
                    "event_types": ["message.delivery", "message.bounce"],
                    "auth_type": "basic",
                    "has_auth_credentials": true,
                    "last_successful_at": "2024-01-15T10:30:00+00:00",
                    "last_failure_at": null,
                    "last_status": "success"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "description": "Webhook not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Webhook not found.",
                  "error_code": "not_found"
                }
              }
            }
          },
          "500": {
            "description": "Server error - Failed to retrieve webhook",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Failed to retrieve webhook. Please try again later.",
                  "error_code": "send_error"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "updateWebhook",
        "summary": "Update Webhook",
        "description": "Update an existing webhook. Only the fields provided will be updated (partial update). You can change the name, target URL, authentication, events, or active status.",
        "tags": ["Webhooks"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "webhookId",
            "in": "path",
            "required": true,
            "description": "The webhook ID to update",
            "schema": {
              "type": "string",
              "example": "webhook-abc123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateWebhookRequest"
              },
              "example": {
                "name": "Updated Webhook Name",
                "active": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShowWebhookResponse"
                },
                "example": {
                  "message": "Webhook updated successfully.",
                  "data": {
                    "id": "webhook-abc123",
                    "name": "Updated Webhook Name",
                    "url": "https://example.com/webhook",
                    "enabled": false,
                    "event_types": ["message.delivery", "message.bounce"],
                    "auth_type": "basic",
                    "has_auth_credentials": true,
                    "last_successful_at": "2024-01-15T10:30:00+00:00",
                    "last_failure_at": null,
                    "last_status": "success"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid webhook configuration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Invalid webhook configuration",
                  "error_code": "send_error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "description": "Webhook not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Webhook not found.",
                  "error_code": "not_found"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "500": {
            "description": "Server error - Failed to update webhook",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Failed to update webhook. Please try again later.",
                  "error_code": "send_error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteWebhook",
        "summary": "Delete Webhook",
        "description": "Delete a webhook. This removes the webhook from SparkPost and it will no longer receive event notifications.",
        "tags": ["Webhooks"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "webhookId",
            "in": "path",
            "required": true,
            "description": "The webhook ID to delete",
            "schema": {
              "type": "string",
              "example": "webhook-abc123"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "message": "Webhook deleted successfully."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "description": "Webhook not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Webhook not found.",
                  "error_code": "not_found"
                }
              }
            }
          },
          "422": {
            "description": "Validation error - Invalid webhook ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                },
                "example": {
                  "message": "Validation failed.",
                  "error_code": "validation_error",
                  "errors": {
                    "webhookId": ["The webhook ID is required."]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error - Failed to delete webhook",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Failed to delete webhook. Please try again later.",
                  "error_code": "send_error"
                }
              }
            }
          }
        }
      }
    },
    "/templates": {
      "get": {
        "operationId": "listTemplates",
        "summary": "List Templates",
        "description": "Retrieve a paginated list of email templates for a project. If `project_id` is not provided, templates from the team's default project will be returned.",
        "tags": ["Templates"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "project_id",
            "in": "query",
            "description": "Project ID to retrieve templates from. If not provided, uses the team's default project.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "description": "Number of results per page (1-100)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of templates retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListTemplatesResponse"
                },
                "example": {
                  "message": "Templates retrieved successfully.",
                  "data": {
                    "templates": [
                      {
                        "id": 1,
                        "name": "Welcome Email",
                        "slug": "welcome-email",
                        "project_id": 5,
                        "folder_id": 10,
                        "created_at": "2025-01-15T10:00:00+00:00",
                        "updated_at": "2025-01-20T14:30:00+00:00"
                      }
                    ],
                    "pagination": {
                      "total": 42,
                      "per_page": 25,
                      "current_page": 1,
                      "last_page": 2
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "description": "Project not found or no default project configured",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "project_not_found": {
                    "summary": "Project not found",
                    "value": {
                      "message": "Project with ID '123' was not found or you don't have access to it.",
                      "error_code": "not_found"
                    }
                  },
                  "no_default_project": {
                    "summary": "No default project configured",
                    "value": {
                      "message": "No default project is configured for this team.",
                      "error_code": "not_found"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                },
                "example": {
                  "message": "Validation failed.",
                  "error_code": "validation_error",
                  "errors": {
                    "project_id": ["The project_id parameter must be an integer."]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Failed to retrieve templates. Please try again later.",
                  "error_code": "send_error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createTemplate",
        "summary": "Create Template",
        "description": "Create a new email template with HTML or Topol editor JSON content. Automatically creates and publishes a template version with extracted merge tags.",
        "tags": ["Templates"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTemplateRequest"
              },
              "examples": {
                "with_json": {
                  "summary": "Create with Topol JSON",
                  "value": {
                    "name": "Welcome Email",
                    "json": "{\"tagName\":\"mj-container\",\"children\":[{\"tagName\":\"mj-text\",\"content\":\"Hello {{FIRST_NAME}}!\"}]}"
                  }
                },
                "with_html": {
                  "summary": "Create with custom HTML",
                  "value": {
                    "name": "Newsletter",
                    "html": "<html><body><p>Hello {{NAME}}, your order {{ORDER_ID}} is ready!</p></body></html>"
                  }
                },
                "with_project_and_folder": {
                  "summary": "Create in specific project and folder",
                  "value": {
                    "name": "Invoice Email",
                    "project_id": 5,
                    "folder_id": 10,
                    "html": "<html><body><p>Invoice for {{CUSTOMER_NAME}}</p></body></html>"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Template created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateTemplateResponse"
                },
                "example": {
                  "message": "Template created successfully.",
                  "data": {
                    "id": 123,
                    "name": "Welcome Email",
                    "slug": "welcome-email",
                    "project_id": 5,
                    "folder_id": 10,
                    "active_version": 1,
                    "merge_tags": [
                      {
                        "key": "FIRST_NAME",
                        "required": true
                      }
                    ],
                    "created_at": "2026-01-28T12:00:00+00:00"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "description": "Project or folder not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "project_not_found": {
                    "summary": "Project not found",
                    "value": {
                      "message": "Project with ID '123' was not found or you don't have access to it.",
                      "error_code": "not_found"
                    }
                  },
                  "no_default_project": {
                    "summary": "No default project configured",
                    "value": {
                      "message": "No default project is configured for this team.",
                      "error_code": "not_found"
                    }
                  },
                  "folder_not_found": {
                    "summary": "Folder not found",
                    "value": {
                      "message": "Folder with ID '456' was not found in the specified project.",
                      "error_code": "not_found"
                    }
                  },
                  "no_folders": {
                    "summary": "No folders in project",
                    "value": {
                      "message": "Project with ID '123' has no folders. Please create a folder first.",
                      "error_code": "not_found"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                },
                "examples": {
                  "name_required": {
                    "summary": "Name is required",
                    "value": {
                      "message": "Validation failed.",
                      "error_code": "validation_error",
                      "errors": {
                        "name": ["The name field is required."]
                      }
                    }
                  },
                  "no_content": {
                    "summary": "No content provided",
                    "value": {
                      "message": "Validation failed.",
                      "error_code": "validation_error",
                      "errors": {
                        "html": ["Either html or json content is required."]
                      }
                    }
                  },
                  "both_content": {
                    "summary": "Both html and json provided",
                    "value": {
                      "message": "Validation failed.",
                      "error_code": "validation_error",
                      "errors": {
                        "json": ["The json and html fields are mutually exclusive. Provide only one."]
                      }
                    }
                  },
                  "invalid_json": {
                    "summary": "Invalid JSON syntax",
                    "value": {
                      "message": "Validation failed.",
                      "error_code": "validation_error",
                      "errors": {
                        "json": ["The provided JSON is not valid."]
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Failed to create template. Please try again later.",
                  "error_code": "send_error"
                }
              }
            }
          }
        }
      }
    },
    "/templates/{slug}": {
      "get": {
        "operationId": "getTemplate",
        "summary": "Get Template",
        "description": "Retrieve a single email template by its slug. If `project_id` is not provided, the template will be looked up in the team's default project.",
        "tags": ["Templates"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The template slug (URL-friendly identifier)",
            "schema": {
              "type": "string",
              "example": "welcome-email"
            }
          },
          {
            "name": "project_id",
            "in": "query",
            "description": "Project ID to retrieve the template from. If not provided, uses the team's default project.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Template retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShowTemplateResponse"
                },
                "example": {
                  "message": "Template retrieved successfully.",
                  "data": {
                    "id": 1,
                    "name": "Welcome Email",
                    "slug": "welcome-email",
                    "project_id": 5,
                    "folder_id": 10,
                    "active_version": 2,
                    "versions_count": 3,
                    "created_at": "2025-01-15T10:00:00+00:00",
                    "updated_at": "2025-01-20T14:30:00+00:00"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "description": "Template or project not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "template_not_found": {
                    "summary": "Template not found",
                    "value": {
                      "message": "Template with slug 'welcome-email' was not found.",
                      "error_code": "not_found"
                    }
                  },
                  "project_not_found": {
                    "summary": "Project not found",
                    "value": {
                      "message": "Project with ID '123' was not found or you don't have access to it.",
                      "error_code": "not_found"
                    }
                  },
                  "no_default_project": {
                    "summary": "No default project configured",
                    "value": {
                      "message": "No default project is configured for this team.",
                      "error_code": "not_found"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                },
                "example": {
                  "message": "Validation failed.",
                  "error_code": "validation_error",
                  "errors": {
                    "project_id": ["The project_id parameter must be an integer."]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Failed to retrieve template. Please try again later.",
                  "error_code": "send_error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteTemplate",
        "summary": "Delete Template",
        "description": "Permanently delete an email template and all its versions. If `project_id` is not provided, the template will be looked up in the team's default project.",
        "tags": ["Templates"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The template slug (URL-friendly identifier)",
            "schema": {
              "type": "string",
              "example": "welcome-email"
            }
          },
          {
            "name": "project_id",
            "in": "query",
            "description": "Project ID to delete the template from. If not provided, uses the team's default project.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Template deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteTemplateResponse"
                },
                "example": {
                  "message": "Template deleted successfully."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "description": "Template or project not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "template_not_found": {
                    "summary": "Template not found",
                    "value": {
                      "message": "Template with slug 'welcome-email' was not found.",
                      "error_code": "not_found"
                    }
                  },
                  "project_not_found": {
                    "summary": "Project not found",
                    "value": {
                      "message": "Project with ID '123' was not found or you don't have access to it.",
                      "error_code": "not_found"
                    }
                  },
                  "no_default_project": {
                    "summary": "No default project configured",
                    "value": {
                      "message": "No default project is configured for this team.",
                      "error_code": "not_found"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                },
                "example": {
                  "message": "Validation failed.",
                  "error_code": "validation_error",
                  "errors": {
                    "project_id": ["The project_id parameter must be an integer."]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Failed to delete template. Please try again later.",
                  "error_code": "send_error"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "updateTemplate",
        "summary": "Update Template",
        "description": "Update an existing email template's name and/or content. If content (html or json) is provided, a new active version will be created with extracted merge tags. If `project_id` is not provided, the template will be looked up in the team's default project.",
        "tags": ["Templates"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The template slug (URL-friendly identifier)",
            "schema": {
              "type": "string",
              "example": "welcome-email"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateTemplateRequest"
              },
              "examples": {
                "update_name": {
                  "summary": "Update template name only",
                  "value": {
                    "name": "Updated Welcome Email"
                  }
                },
                "update_html": {
                  "summary": "Update with new HTML content",
                  "value": {
                    "html": "<html><body><p>Hello {{NAME}}, welcome aboard!</p></body></html>"
                  }
                },
                "update_json": {
                  "summary": "Update with new Topol JSON content",
                  "value": {
                    "json": "{\"tagName\":\"mj-container\",\"children\":[{\"tagName\":\"mj-text\",\"content\":\"Hello {{FIRST_NAME}}!\"}]}"
                  }
                },
                "update_name_and_content": {
                  "summary": "Update name and content together",
                  "value": {
                    "name": "New Newsletter",
                    "html": "<html><body><p>Welcome {{SUBSCRIBER_NAME}}!</p></body></html>"
                  }
                },
                "update_with_project": {
                  "summary": "Update template in specific project",
                  "value": {
                    "project_id": 5,
                    "name": "Renamed Template"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Template updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdateTemplateResponse"
                },
                "example": {
                  "message": "Template updated successfully.",
                  "data": {
                    "id": 123,
                    "name": "Updated Welcome Email",
                    "slug": "welcome-email",
                    "project_id": 5,
                    "folder_id": 10,
                    "active_version": 2,
                    "merge_tags": [
                      {
                        "key": "NAME",
                        "required": true
                      }
                    ],
                    "created_at": "2026-01-15T10:00:00+00:00",
                    "updated_at": "2026-01-28T14:30:00+00:00"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "description": "Template or project not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "template_not_found": {
                    "summary": "Template not found",
                    "value": {
                      "message": "Template with slug 'welcome-email' was not found.",
                      "error_code": "not_found"
                    }
                  },
                  "project_not_found": {
                    "summary": "Project not found",
                    "value": {
                      "message": "Project with ID '123' was not found or you don't have access to it.",
                      "error_code": "not_found"
                    }
                  },
                  "no_default_project": {
                    "summary": "No default project configured",
                    "value": {
                      "message": "No default project is configured for this team.",
                      "error_code": "not_found"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                },
                "examples": {
                  "both_content": {
                    "summary": "Both html and json provided",
                    "value": {
                      "message": "Validation failed.",
                      "error_code": "validation_error",
                      "errors": {
                        "json": ["The json field prohibits html from being present."]
                      }
                    }
                  },
                  "invalid_json": {
                    "summary": "Invalid JSON syntax",
                    "value": {
                      "message": "Validation failed.",
                      "error_code": "validation_error",
                      "errors": {
                        "json": ["The provided JSON is not valid."]
                      }
                    }
                  },
                  "name_too_long": {
                    "summary": "Name exceeds max length",
                    "value": {
                      "message": "Validation failed.",
                      "error_code": "validation_error",
                      "errors": {
                        "name": ["The name must not be greater than 255 characters."]
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Failed to update template. Please try again later.",
                  "error_code": "send_error"
                }
              }
            }
          }
        }
      }
    },
    "/templates/{slug}/merge-tags": {
      "get": {
        "operationId": "getTemplateMergeTags",
        "summary": "Get Template Merge Tags",
        "description": "Retrieve the merge tags (variables) for a template version. By default, returns merge tags for the active version. Use the `version` parameter to get merge tags for a specific version.",
        "tags": ["Templates"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The template slug (URL-friendly identifier)",
            "schema": {
              "type": "string",
              "example": "welcome-email"
            }
          },
          {
            "name": "project_id",
            "in": "query",
            "description": "Project ID to retrieve the template from. If not provided, uses the team's default project.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "version",
            "in": "query",
            "description": "Template version number. If not provided, uses the active version.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Merge tags retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetMergeTagsResponse"
                },
                "example": {
                  "message": "Merge tags retrieved successfully.",
                  "data": {
                    "template_slug": "welcome-email",
                    "version": 2,
                    "merge_tags": [
                      {
                        "key": "first_name",
                        "required": true
                      },
                      {
                        "key": "company_name",
                        "required": false
                      },
                      {
                        "key": "order_items",
                        "required": false,
                        "children": [
                          {
                            "key": "item_name",
                            "type": "text"
                          },
                          {
                            "key": "item_quantity",
                            "type": "number"
                          },
                          {
                            "key": "item_price",
                            "type": "number"
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "description": "Template, version, or project not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "template_not_found": {
                    "summary": "Template not found",
                    "value": {
                      "message": "Template with slug 'welcome-email' was not found.",
                      "error_code": "not_found"
                    }
                  },
                  "project_not_found": {
                    "summary": "Project not found",
                    "value": {
                      "message": "Project with ID '123' was not found or you don't have access to it.",
                      "error_code": "not_found"
                    }
                  },
                  "no_default_project": {
                    "summary": "No default project configured",
                    "value": {
                      "message": "No default project is configured for this team.",
                      "error_code": "not_found"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                },
                "example": {
                  "message": "Validation failed.",
                  "error_code": "validation_error",
                  "errors": {
                    "version": ["The version parameter must be an integer."]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Failed to retrieve merge tags. Please try again later.",
                  "error_code": "send_error"
                }
              }
            }
          }
        }
      }
    },
    "/domains/{domain}/verify": {
      "post": {
        "operationId": "verifyDomain",
        "summary": "Verify Domain",
        "description": "Verify a domain's DNS records (DKIM and CNAME) with SparkPost. This triggers a verification check and returns the current status of DNS records.",
        "tags": ["Domains"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "path",
            "required": true,
            "description": "The domain name to verify",
            "schema": {
              "type": "string",
              "example": "example.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Domain verification completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyDomainResponse"
                },
                "examples": {
                  "valid": {
                    "summary": "All DNS records valid",
                    "value": {
                      "message": "Domain verification completed.",
                      "data": {
                        "domain": "example.com",
                        "dkim_status": "valid",
                        "cname_status": "valid",
                        "ownership_verified": "true"
                      }
                    }
                  },
                  "unverified": {
                    "summary": "DNS records not configured",
                    "value": {
                      "message": "Domain verification completed.",
                      "data": {
                        "domain": "example.com",
                        "dkim_status": "unverified",
                        "cname_status": "unverified",
                        "ownership_verified": null,
                        "dns": {
                          "dkim_record": null,
                          "cname_record": null,
                          "dkim_error": "DKIM record not found",
                          "cname_error": "CNAME record not found"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "description": "Domain not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Domain not found.",
                  "error_code": "not_found"
                }
              }
            }
          },
          "422": {
            "description": "Validation error - Invalid domain format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                },
                "example": {
                  "message": "Validation failed.",
                  "error_code": "validation_error",
                  "errors": {
                    "domain": ["The domain must be a valid domain name (e.g., example.com)."]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error - Failed to verify domain",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "message": "Failed to verify domain. Please try again later.",
                  "error_code": "send_error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key for authentication"
      }
    },
    "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"
            }
          }
        }
      }
    },
    "schemas": {
      "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\n\nWelcome!"
          },
          "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"
            }
          }
        }
      },
      "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..."
          }
        }
      },
      "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
              }
            }
          }
        }
      },
      "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"
          }
        }
      },
      "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.\n\n| Code | HTTP Status | Description |\n|------|-------------|-------------|\n| `validation_error` | 422 | Request validation failed. Check the `errors` object for field-specific messages. |\n| `invalid_domain` | 400 | The sender domain could not be determined from the email address. |\n| `unconfigured_domain` | 400 | The sender domain is not configured or approved for sending. |\n| `send_error` | 400, 500 | General error during email send preparation or domain registration. |\n| `transmission_failed` | 502 | Email transmission to the upstream provider failed. |\n| `resource_already_exists` | 409 | The resource (e.g., domain) already exists. |\n| `template_not_found` | 404 | The specified template, project, or template version was not found. |\n| `quota_exceeded` | 429 | Monthly sending quota exceeded. Upgrade your plan to continue sending. |\n| `daily_quota_exceeded` | 429 | Daily sending quota exceeded. Try again tomorrow. |",
        "enum": ["validation_error", "invalid_domain", "unconfigured_domain", "send_error", "transmission_failed", "resource_already_exists", "template_not_found", "not_found", "quota_exceeded", "daily_quota_exceeded"],
        "example": "invalid_domain"
      },
      "StoreDomainRequest": {
        "type": "object",
        "description": "Request to create a new sending domain",
        "required": ["domain"],
        "properties": {
          "domain": {
            "type": "string",
            "maxLength": 255,
            "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z]{2,})+$",
            "description": "The domain name to register (e.g., example.com)",
            "example": "example.com"
          }
        }
      },
      "StoreDomainResponse": {
        "type": "object",
        "description": "Response after successfully creating a domain",
        "required": ["message", "data"],
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable success message",
            "example": "Domain created successfully."
          },
          "data": {
            "$ref": "#/components/schemas/DomainView"
          }
        }
      },
      "DomainView": {
        "type": "object",
        "description": "View of a sending domain",
        "required": ["domain", "status", "status_label"],
        "properties": {
          "domain": {
            "type": "string",
            "description": "The domain name",
            "example": "example.com"
          },
          "status": {
            "type": "string",
            "enum": ["pending", "approved", "blocked"],
            "description": "Current status of the domain",
            "example": "pending"
          },
          "status_label": {
            "type": "string",
            "description": "Human-readable status label",
            "example": "Pending Review"
          },
          "dkim": {
            "type": ["object", "null"],
            "description": "DKIM configuration for the domain",
            "properties": {
              "public": {
                "type": "string",
                "description": "Public DKIM key"
              },
              "selector": {
                "type": "string",
                "description": "DKIM selector"
              },
              "headers": {
                "type": "string",
                "description": "Headers to sign"
              }
            }
          }
        }
      },
      "ListDomainsResponse": {
        "type": "object",
        "description": "Response containing a list of domains",
        "required": ["message", "data"],
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable response message",
            "example": "Domains retrieved successfully."
          },
          "data": {
            "type": "object",
            "required": ["domains"],
            "properties": {
              "domains": {
                "type": "array",
                "description": "List of domains",
                "items": {
                  "$ref": "#/components/schemas/DomainListItemView"
                }
              }
            }
          }
        }
      },
      "DomainListItemView": {
        "type": "object",
        "description": "View of a domain in the list response",
        "required": ["domain", "status", "status_label", "can_send", "created_at", "updated_at"],
        "properties": {
          "domain": {
            "type": "string",
            "description": "The domain name",
            "example": "example.com"
          },
          "status": {
            "type": "string",
            "enum": ["pending", "approved", "blocked"],
            "description": "Current status of the domain",
            "example": "approved"
          },
          "status_label": {
            "type": "string",
            "description": "Human-readable status label",
            "example": "Approved"
          },
          "can_send": {
            "type": "boolean",
            "description": "Whether the domain can be used for sending emails",
            "example": true
          },
          "cname_status": {
            "type": ["string", "null"],
            "description": "CNAME verification status",
            "example": "valid"
          },
          "dkim_status": {
            "type": ["string", "null"],
            "description": "DKIM verification status",
            "example": "valid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the domain was created",
            "example": "2024-01-15T10:30:00+00:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the domain was last updated",
            "example": "2024-01-16T14:45:00+00:00"
          }
        }
      },
      "ShowDomainResponse": {
        "type": "object",
        "description": "Response containing a single domain with full details",
        "required": ["message", "data"],
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable response message",
            "example": "Domain retrieved successfully."
          },
          "data": {
            "$ref": "#/components/schemas/DomainDetailView"
          }
        }
      },
      "DomainDetailView": {
        "type": "object",
        "description": "Detailed view of a single domain",
        "required": ["domain", "status", "status_label", "can_send", "created_at", "updated_at"],
        "properties": {
          "domain": {
            "type": "string",
            "description": "The domain name",
            "example": "example.com"
          },
          "status": {
            "type": "string",
            "enum": ["pending", "approved", "blocked"],
            "description": "Current status of the domain",
            "example": "approved"
          },
          "status_label": {
            "type": "string",
            "description": "Human-readable status label",
            "example": "Approved"
          },
          "can_send": {
            "type": "boolean",
            "description": "Whether the domain can be used for sending emails",
            "example": true
          },
          "cname_status": {
            "type": ["string", "null"],
            "description": "CNAME verification status",
            "example": "valid"
          },
          "dkim_status": {
            "type": ["string", "null"],
            "description": "DKIM verification status",
            "example": "valid"
          },
          "tracking_domain": {
            "type": ["string", "null"],
            "description": "Associated tracking domain for click/open tracking",
            "example": "tracking.example.com"
          },
          "dns": {
            "type": ["object", "null"],
            "description": "DNS records for domain verification",
            "properties": {
              "dkim": {
                "type": "object",
                "description": "DKIM DNS record details",
                "properties": {
                  "selector": {
                    "type": "string",
                    "description": "DKIM selector",
                    "example": "scph0123"
                  },
                  "public": {
                    "type": "string",
                    "description": "DKIM public key",
                    "example": "MIGfMA0GCSqGSIb3DQEBA..."
                  },
                  "headers": {
                    "type": "string",
                    "description": "Headers included in DKIM signature",
                    "example": "from:to:subject:date"
                  }
                }
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the domain was created",
            "example": "2024-01-15T10:30:00+00:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the domain was last updated",
            "example": "2024-01-16T14:45:00+00:00"
          }
        }
      },
      "VerifyDomainResponse": {
        "type": "object",
        "description": "Response containing domain verification results",
        "required": ["message", "data"],
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable response message",
            "example": "Domain verification completed."
          },
          "data": {
            "$ref": "#/components/schemas/DomainVerificationView"
          }
        }
      },
      "DomainVerificationView": {
        "type": "object",
        "description": "Domain verification status and DNS details",
        "required": ["domain", "dkim_status", "cname_status"],
        "properties": {
          "domain": {
            "type": "string",
            "description": "The domain name",
            "example": "example.com"
          },
          "dkim_status": {
            "type": "string",
            "description": "DKIM verification status",
            "enum": ["valid", "unverified", "invalid"],
            "example": "valid"
          },
          "cname_status": {
            "type": "string",
            "description": "CNAME verification status",
            "enum": ["valid", "unverified", "invalid"],
            "example": "valid"
          },
          "ownership_verified": {
            "type": ["string", "null"],
            "description": "Whether domain ownership has been verified",
            "example": "true"
          },
          "dns": {
            "$ref": "#/components/schemas/DomainDnsVerificationView"
          }
        }
      },
      "DomainDnsVerificationView": {
        "type": "object",
        "description": "DNS verification error details",
        "properties": {
          "dkim_record": {
            "type": ["string", "null"],
            "description": "Found DKIM record value",
            "example": null
          },
          "cname_record": {
            "type": ["string", "null"],
            "description": "Found CNAME record value",
            "example": null
          },
          "dkim_error": {
            "type": ["string", "null"],
            "description": "DKIM verification error message",
            "example": "DKIM record not found"
          },
          "cname_error": {
            "type": ["string", "null"],
            "description": "CNAME verification error message",
            "example": "CNAME record not found"
          }
        }
      },
      "UpdateWebhookRequest": {
        "type": "object",
        "description": "Request body for updating a webhook. Only provided fields will be updated.",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the webhook",
            "maxLength": 255,
            "example": "Updated Webhook Name"
          },
          "target": {
            "type": "string",
            "format": "uri",
            "description": "URL where webhook events will be sent",
            "maxLength": 2048,
            "example": "https://example.com/webhook"
          },
          "auth_type": {
            "type": "string",
            "description": "Authentication type for the webhook",
            "enum": ["none", "basic", "oauth2"],
            "example": "none"
          },
          "auth_username": {
            "type": "string",
            "description": "Username for basic authentication",
            "maxLength": 255
          },
          "auth_password": {
            "type": "string",
            "description": "Password for basic authentication",
            "maxLength": 255
          },
          "oauth_token_url": {
            "type": "string",
            "format": "uri",
            "description": "OAuth2 token URL",
            "maxLength": 2048
          },
          "oauth_client_id": {
            "type": "string",
            "description": "OAuth2 client ID",
            "maxLength": 255
          },
          "oauth_client_secret": {
            "type": "string",
            "description": "OAuth2 client secret",
            "maxLength": 255
          },
          "events": {
            "type": "array",
            "description": "Event types that trigger the webhook",
            "minItems": 1,
            "items": {
              "type": "string",
              "enum": [
                "message.injection",
                "message.delivery",
                "message.bounce",
                "message.delay",
                "message.out_of_band",
                "message.spam_complaint",
                "message.policy_rejection",
                "engagament.click",
                "engagament.open",
                "engagament.initial_open",
                "engagament.amp_click",
                "engagament.amp_open",
                "engagament.amp_initial_open",
                "generation.generation_failure",
                "generation.generation_rejection",
                "unsubscribe.list_unsubscribe",
                "unsubscribe.link_unsubscribe",
                "relay.relay_injection",
                "relay.relay_rejection",
                "relay.relay_delivery",
                "relay.relay_tempfail",
                "relay.relay_permfail"
              ]
            },
            "example": ["message.delivery", "message.bounce"]
          },
          "active": {
            "type": "boolean",
            "description": "Whether the webhook is enabled",
            "example": true
          }
        }
      },
      "ListWebhooksResponse": {
        "type": "object",
        "description": "Response containing a list of webhooks",
        "required": ["message", "data"],
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable response message",
            "example": "Webhooks retrieved successfully."
          },
          "data": {
            "type": "object",
            "required": ["webhooks"],
            "properties": {
              "webhooks": {
                "type": "array",
                "description": "List of webhooks",
                "items": {
                  "$ref": "#/components/schemas/WebhookView"
                }
              }
            }
          }
        }
      },
      "ShowWebhookResponse": {
        "type": "object",
        "description": "Response containing a single webhook",
        "required": ["message", "data"],
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable response message",
            "example": "Webhook retrieved successfully."
          },
          "data": {
            "$ref": "#/components/schemas/WebhookView"
          }
        }
      },
      "StoreWebhookRequest": {
        "type": "object",
        "description": "Request body for creating a webhook",
        "required": ["name", "url", "auth_type", "events_mode"],
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the webhook",
            "maxLength": 255,
            "example": "Order Notifications"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "URL where webhook events will be sent",
            "maxLength": 2048,
            "example": "https://example.com/webhook"
          },
          "auth_type": {
            "type": "string",
            "enum": ["none", "basic", "oauth2"],
            "description": "Authentication type for the webhook",
            "example": "basic"
          },
          "auth_username": {
            "type": "string",
            "description": "Username for basic authentication (required when auth_type is 'basic')",
            "maxLength": 255,
            "example": "user"
          },
          "auth_password": {
            "type": "string",
            "description": "Password for basic authentication (required when auth_type is 'basic')",
            "maxLength": 255,
            "example": "secret"
          },
          "oauth_client_id": {
            "type": "string",
            "description": "OAuth2 client ID (required when auth_type is 'oauth2')",
            "maxLength": 255
          },
          "oauth_client_secret": {
            "type": "string",
            "description": "OAuth2 client secret (required when auth_type is 'oauth2')",
            "maxLength": 255
          },
          "oauth_token_url": {
            "type": "string",
            "format": "uri",
            "description": "OAuth2 token URL (required when auth_type is 'oauth2')",
            "maxLength": 2048
          },
          "events_mode": {
            "type": "string",
            "enum": ["all", "selected"],
            "description": "Whether to receive all events or only selected ones",
            "example": "selected"
          },
          "events": {
            "type": "array",
            "description": "List of event types to receive (required when events_mode is 'selected')",
            "items": {
              "type": "string"
            },
            "example": ["delivery", "bounce"]
          }
        }
      },
      "StoreWebhookResponse": {
        "type": "object",
        "description": "Response after creating a webhook",
        "required": ["message", "data"],
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable response message",
            "example": "Webhook created successfully."
          },
          "data": {
            "$ref": "#/components/schemas/WebhookView"
          }
        }
      },
      "ListTemplatesResponse": {
        "type": "object",
        "description": "Response containing a paginated list of templates",
        "required": ["message", "data"],
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable response message",
            "example": "Templates retrieved successfully."
          },
          "data": {
            "type": "object",
            "required": ["templates", "pagination"],
            "properties": {
              "templates": {
                "type": "array",
                "description": "List of templates",
                "items": {
                  "$ref": "#/components/schemas/TemplateView"
                }
              },
              "pagination": {
                "$ref": "#/components/schemas/TemplatesPagination"
              }
            }
          }
        }
      },
      "TemplateView": {
        "type": "object",
        "description": "View of an email template",
        "required": ["id", "name", "slug", "project_id", "folder_id", "created_at", "updated_at"],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Unique identifier for the template",
            "example": 1
          },
          "name": {
            "type": "string",
            "description": "Name of the template",
            "example": "Welcome Email"
          },
          "slug": {
            "type": "string",
            "description": "URL-friendly identifier for the template",
            "example": "welcome-email"
          },
          "project_id": {
            "type": "integer",
            "description": "ID of the project containing this template",
            "example": 5
          },
          "folder_id": {
            "type": "integer",
            "description": "ID of the folder containing this template",
            "example": 10
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the template was created",
            "example": "2025-01-15T10:00:00+00:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the template was last updated",
            "example": "2025-01-20T14:30:00+00:00"
          }
        }
      },
      "TemplatesPagination": {
        "type": "object",
        "description": "Pagination information for templates list",
        "required": ["total", "per_page", "current_page", "last_page"],
        "properties": {
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Total number of templates",
            "example": 42
          },
          "per_page": {
            "type": "integer",
            "minimum": 1,
            "description": "Number of templates per page",
            "example": 25
          },
          "current_page": {
            "type": "integer",
            "minimum": 1,
            "description": "Current page number",
            "example": 1
          },
          "last_page": {
            "type": "integer",
            "minimum": 1,
            "description": "Last page number",
            "example": 2
          }
        }
      },
      "ShowTemplateResponse": {
        "type": "object",
        "description": "Response containing a single template with details",
        "required": ["message", "data"],
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable response message",
            "example": "Template retrieved successfully."
          },
          "data": {
            "$ref": "#/components/schemas/TemplateDetailView"
          }
        }
      },
      "TemplateDetailView": {
        "type": "object",
        "description": "Detailed view of an email template",
        "required": ["id", "name", "slug", "project_id", "folder_id", "active_version", "versions_count", "created_at", "updated_at"],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Unique identifier for the template",
            "example": 1
          },
          "name": {
            "type": "string",
            "description": "Name of the template",
            "example": "Welcome Email"
          },
          "slug": {
            "type": "string",
            "description": "URL-friendly identifier for the template",
            "example": "welcome-email"
          },
          "project_id": {
            "type": "integer",
            "description": "ID of the project containing this template",
            "example": 5
          },
          "folder_id": {
            "type": "integer",
            "description": "ID of the folder containing this template",
            "example": 10
          },
          "active_version": {
            "type": ["integer", "null"],
            "description": "Version number of the currently active template version, or null if no version is active",
            "example": 2
          },
          "versions_count": {
            "type": "integer",
            "minimum": 0,
            "description": "Total number of versions for this template",
            "example": 3
          },
          "html": {
            "type": ["string", "null"],
            "description": "The HTML content of the active template version, or null if no active version exists",
            "example": "<html><body><h1>Welcome!</h1></body></html>"
          },
          "json": {
            "type": ["string", "null"],
            "description": "The JSON definition of the active template version (for visual editor templates), or null if no active version exists or it's a custom HTML template",
            "example": "{\"tagName\":\"mj-body\",\"children\":[...]}"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the template was created",
            "example": "2025-01-15T10:00:00+00:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the template was last updated",
            "example": "2025-01-20T14:30:00+00:00"
          }
        }
      },
      "CreateTemplateRequest": {
        "type": "object",
        "description": "Request to create a new email template. Provide either `html` for custom HTML templates or `json` for Topol visual editor templates.",
        "required": ["name"],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255,
            "description": "Name of the template",
            "example": "Welcome Email"
          },
          "project_id": {
            "type": "integer",
            "minimum": 1,
            "description": "Project ID to create the template in. If not provided, uses the team's default project.",
            "example": 5
          },
          "folder_id": {
            "type": "integer",
            "minimum": 1,
            "description": "Folder ID to create the template in. If not provided, uses the first folder in the project.",
            "example": 10
          },
          "html": {
            "type": "string",
            "description": "HTML content for custom HTML templates. Required if `json` is not provided. Mutually exclusive with `json`.",
            "example": "<html><body><p>Hello {{NAME}}!</p></body></html>"
          },
          "json": {
            "type": "string",
            "description": "JSON content for Topol visual editor templates. Required if `html` is not provided. Mutually exclusive with `html`.",
            "example": "{\"tagName\":\"mj-container\",\"children\":[{\"tagName\":\"mj-text\",\"content\":\"Hello {{FIRST_NAME}}!\"}]}"
          }
        }
      },
      "CreateTemplateResponse": {
        "type": "object",
        "description": "Response after successfully creating a template",
        "required": ["message", "data"],
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable response message",
            "example": "Template created successfully."
          },
          "data": {
            "$ref": "#/components/schemas/CreatedTemplateView"
          }
        }
      },
      "DeleteTemplateResponse": {
        "type": "object",
        "description": "Response after successfully deleting a template",
        "required": ["message"],
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable response message",
            "example": "Template deleted successfully."
          }
        }
      },
      "UpdateTemplateRequest": {
        "type": "object",
        "description": "Request to update an existing email template. All fields are optional - provide only what you want to change. If `html` or `json` is provided, a new active version will be created.",
        "properties": {
          "project_id": {
            "type": "integer",
            "minimum": 1,
            "description": "Project ID to find the template in. If not provided, uses the team's default project.",
            "example": 5
          },
          "name": {
            "type": "string",
            "maxLength": 255,
            "description": "New name for the template",
            "example": "Updated Welcome Email"
          },
          "html": {
            "type": "string",
            "description": "New HTML content for the template. Creates a new active version. Mutually exclusive with `json`.",
            "example": "<html><body><p>Hello {{NAME}}!</p></body></html>"
          },
          "json": {
            "type": "string",
            "description": "New JSON content for Topol visual editor templates. Creates a new active version. Mutually exclusive with `html`.",
            "example": "{\"tagName\":\"mj-container\",\"children\":[{\"tagName\":\"mj-text\",\"content\":\"Hello {{FIRST_NAME}}!\"}]}"
          }
        }
      },
      "UpdateTemplateResponse": {
        "type": "object",
        "description": "Response after successfully updating a template",
        "required": ["message", "data"],
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable response message",
            "example": "Template updated successfully."
          },
          "data": {
            "$ref": "#/components/schemas/UpdatedTemplateView"
          }
        }
      },
      "UpdatedTemplateView": {
        "type": "object",
        "description": "View of an updated template",
        "required": ["id", "name", "slug", "project_id", "folder_id", "active_version", "merge_tags", "created_at", "updated_at"],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Unique identifier for the template",
            "example": 123
          },
          "name": {
            "type": "string",
            "description": "Name of the template",
            "example": "Updated Welcome Email"
          },
          "slug": {
            "type": "string",
            "description": "URL-friendly identifier for the template",
            "example": "welcome-email"
          },
          "project_id": {
            "type": "integer",
            "description": "ID of the project containing this template",
            "example": 5
          },
          "folder_id": {
            "type": "integer",
            "description": "ID of the folder containing this template",
            "example": 10
          },
          "active_version": {
            "type": "integer",
            "description": "Version number of the active template version",
            "example": 2
          },
          "merge_tags": {
            "type": "array",
            "description": "List of merge tags extracted from the template content",
            "items": {
              "$ref": "#/components/schemas/MergeTagView"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the template was created",
            "example": "2026-01-15T10:00:00+00:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the template was last updated",
            "example": "2026-01-28T14:30:00+00:00"
          }
        }
      },
      "CreatedTemplateView": {
        "type": "object",
        "description": "View of a newly created template",
        "required": ["id", "name", "slug", "project_id", "folder_id", "active_version", "merge_tags", "created_at"],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Unique identifier for the template",
            "example": 123
          },
          "name": {
            "type": "string",
            "description": "Name of the template",
            "example": "Welcome Email"
          },
          "slug": {
            "type": "string",
            "description": "URL-friendly identifier for the template",
            "example": "welcome-email"
          },
          "project_id": {
            "type": "integer",
            "description": "ID of the project containing this template",
            "example": 5
          },
          "folder_id": {
            "type": "integer",
            "description": "ID of the folder containing this template",
            "example": 10
          },
          "active_version": {
            "type": "integer",
            "description": "Version number of the active template version",
            "example": 1
          },
          "merge_tags": {
            "type": "array",
            "description": "List of merge tags extracted from the template content",
            "items": {
              "$ref": "#/components/schemas/MergeTagView"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the template was created",
            "example": "2026-01-28T12:00:00+00:00"
          }
        }
      },
      "GetMergeTagsResponse": {
        "type": "object",
        "description": "Response containing merge tags for a template version",
        "required": ["message", "data"],
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable response message",
            "example": "Merge tags retrieved successfully."
          },
          "data": {
            "$ref": "#/components/schemas/MergeTagsListView"
          }
        }
      },
      "MergeTagsListView": {
        "type": "object",
        "description": "Merge tags for a template version",
        "required": ["template_slug", "version", "merge_tags"],
        "properties": {
          "template_slug": {
            "type": "string",
            "description": "The template slug",
            "example": "welcome-email"
          },
          "version": {
            "type": "integer",
            "description": "The template version number",
            "example": 2
          },
          "merge_tags": {
            "type": "array",
            "description": "List of merge tags in this template version",
            "items": {
              "$ref": "#/components/schemas/MergeTagView"
            }
          }
        }
      },
      "MergeTagView": {
        "type": "object",
        "description": "A single merge tag. Loop merge tags (for iterating over arrays) include a 'children' property with nested field definitions.",
        "required": ["key", "required"],
        "properties": {
          "key": {
            "type": "string",
            "description": "The merge tag key/name used in templates",
            "example": "first_name"
          },
          "required": {
            "type": "boolean",
            "description": "Whether this merge tag is required when sending emails",
            "example": true
          },
          "type": {
            "type": "string",
            "description": "The data type of the merge tag (only present for loop children)",
            "enum": ["text", "number", "image", "button"],
            "example": "text"
          },
          "children": {
            "type": "array",
            "description": "Child merge tags for loop blocks. Each child represents a field available within the loop iteration.",
            "items": {
              "$ref": "#/components/schemas/MergeTagChild"
            }
          }
        }
      },
      "MergeTagChild": {
        "type": "object",
        "description": "A child merge tag within a loop block",
        "required": ["key"],
        "properties": {
          "key": {
            "type": "string",
            "description": "The child merge tag key/name",
            "example": "item_name"
          },
          "type": {
            "type": "string",
            "description": "The data type of the child merge tag",
            "enum": ["text", "number", "image", "button"],
            "example": "text"
          }
        }
      },
      "WebhookView": {
        "type": "object",
        "description": "View of a webhook",
        "required": ["id", "name", "url", "enabled", "auth_type", "has_auth_credentials"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the webhook",
            "example": "webhook-abc123"
          },
          "name": {
            "type": "string",
            "description": "Name of the webhook",
            "example": "Order Notifications"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "URL where webhook events will be sent",
            "example": "https://example.com/webhook"
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether the webhook is enabled",
            "example": true
          },
          "event_types": {
            "type": ["array", "null"],
            "description": "Specific event types the webhook receives (null if all events)",
            "items": {
              "type": "string"
            },
            "example": ["message.delivery", "message.bounce"]
          },
          "auth_type": {
            "type": "string",
            "description": "Authentication type for the webhook (none, basic, oauth2)",
            "example": "basic"
          },
          "has_auth_credentials": {
            "type": "boolean",
            "description": "Whether authentication credentials are configured",
            "example": true
          },
          "last_successful_at": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "Timestamp of the last successful webhook delivery",
            "example": "2024-01-15T10:30:00+00:00"
          },
          "last_failure_at": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "Timestamp of the last failed webhook delivery",
            "example": null
          },
          "last_status": {
            "type": ["string", "null"],
            "description": "Status of the last delivery attempt (success or failure)",
            "enum": ["success", "failure", null],
            "example": "success"
          }
        }
      },
      "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"
              }
            }
          }
        ]
      },
      "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"
                }
              }
            }
          }
        }
      },
      "GetEmailDetailResponse": {
        "type": "object",
        "required": ["message", "data"],
        "description": "Email detail response. Uses the same data shape as the scheduled transmission detail — see `ShowScheduledTransmissionResponse` for field descriptions.",
        "properties": {
          "message": {
            "type": "string",
            "example": "Email 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 (same as the `requestId` returned when the email was sent).",
                "example": "12345678901234567890"
              },
              "state": {
                "type": "string",
                "description": "Derived delivery state based on events. `scheduled` — injected but not yet delivered. `delivered` — successfully delivered. `bounced` — rejected by recipient server. `failed` — generation or policy failure.",
                "enum": ["scheduled", "delivered", "bounced", "failed"],
                "example": "delivered"
              },
              "scheduled_at": {
                "type": ["string", "null"],
                "format": "date-time",
                "description": "The scheduled delivery time, if the email was scheduled. Usually `null` for immediately-sent emails.",
                "example": null
              },
              "from": {
                "type": "string",
                "format": "email",
                "description": "Sender email address.",
                "example": "sender@example.com"
              },
              "from_name": {
                "type": ["string", "null"],
                "description": "Sender display name.",
                "example": null
              },
              "subject": {
                "type": "string",
                "description": "Email subject line.",
                "example": "Welcome to Lettr"
              },
              "recipients": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "email"
                },
                "description": "Unique list of recipient email addresses derived from events.",
                "example": ["recipient@example.com"]
              },
              "num_recipients": {
                "type": "integer",
                "description": "Total number of unique recipients.",
                "example": 1
              },
              "events": {
                "type": "array",
                "description": "Delivery events for this email (injection, delivery, bounce, open, click, etc.).",
                "items": {
                  "$ref": "#/components/schemas/EmailEvent"
                }
              }
            }
          }
        }
      },
      "ListEmailEventsResponse": {
        "type": "object",
        "required": ["message", "data"],
        "properties": {
          "message": {
            "type": "string",
            "example": "Email events retrieved successfully."
          },
          "data": {
            "type": "object",
            "required": ["events"],
            "properties": {
              "events": {
                "type": "object",
                "required": ["data", "total_count", "from", "to", "pagination"],
                "properties": {
                  "data": {
                    "type": "array",
                    "description": "List of email events. Each event contains common fields plus type-specific fields (e.g. bounce events include bounce_class and reason, click events include target_link_url).",
                    "items": {
                      "$ref": "#/components/schemas/EmailEvent"
                    }
                  },
                  "total_count": {
                    "type": "integer",
                    "description": "Total number of events matching the query",
                    "example": 2
                  },
                  "from": {
                    "type": "string",
                    "description": "Start of the date range used for the query",
                    "example": "2024-01-05T00:00:00+00:00"
                  },
                  "to": {
                    "type": "string",
                    "description": "End of the date range used for the query",
                    "example": "2024-01-15T10:35:00+00:00"
                  },
                  "pagination": {
                    "type": "object",
                    "properties": {
                      "next_cursor": {
                        "type": ["string", "null"],
                        "description": "Cursor for the next page of results. Null if no more pages.",
                        "example": null
                      },
                      "per_page": {
                        "type": "integer",
                        "description": "Number of events per page",
                        "example": 25
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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"] }
            }
          }
        ]
      }
    }
  },
  "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"
    }
  ]
}