{"openapi":"3.1.0","info":{"title":"MailtestAPI","description":"REST API for listing, creating, inspecting, updating, and deleting captured emails.","version":"1.0.0"},"servers":[{"url":"https://api.mailtestapi.com","description":"Production"}],"tags":[{"name":"Health","description":"Basic service health checks."},{"name":"Emails","description":"Email capture and message management endpoints."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Provide your API key as a Bearer token."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Alternative header-based API key authentication."}},"schemas":{"HealthResponse":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"]},"Account":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"]},"EmailStatus":{"type":"string","enum":["received","processed","archived"]},"EmailSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"account":{"anyOf":[{"$ref":"#/components/schemas/Account"},{"type":"null"}]},"messageId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sender":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"recipient":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"$ref":"#/components/schemas/EmailStatus"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"labels":{"type":"array","items":{"type":"string"}},"rawSize":{"type":"integer","minimum":0,"maximum":9007199254740991},"receivedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","account","messageId","sender","recipient","subject","status","notes","labels","rawSize","receivedAt","createdAt","updatedAt"]},"ListEmailsResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/EmailSummary"}}},"required":["items"]},"ValidationErrors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"}},"fieldErrors":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["formErrors","fieldErrors"]},"ValidationErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ValidationErrors"}},"required":["error"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"EmailResponse":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/EmailSummary"}},"required":["item"]},"CreateEmailRequest":{"type":"object","properties":{"headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"html":{"anyOf":[{"type":"string"},{"type":"null"}]},"raw":{"type":"string"},"receivedAt":{"type":"string","format":"date-time"},"recipient":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"sender":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"subject":{"anyOf":[{"type":"string","maxLength":998},{"type":"null"}]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["recipient","sender"]},"StoredEmailAttachment":{"type":"object","properties":{"contentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"contentType":{"anyOf":[{"type":"string"},{"type":"null"}]},"disposition":{"anyOf":[{"type":"string"},{"type":"null"}]},"filename":{"anyOf":[{"type":"string"},{"type":"null"}]},"size":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["contentId","contentType","disposition","filename","size"]},"StoredEmailBody":{"type":"object","properties":{"raw":{"type":"string"},"text":{"anyOf":[{"type":"string"},{"type":"null"}]},"html":{"anyOf":[{"type":"string"},{"type":"null"}]},"headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/StoredEmailAttachment"}}},"required":["raw","text","html","headers","attachments"]},"EmailDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"account":{"anyOf":[{"$ref":"#/components/schemas/Account"},{"type":"null"}]},"messageId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sender":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"recipient":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"$ref":"#/components/schemas/EmailStatus"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"labels":{"type":"array","items":{"type":"string"}},"rawSize":{"type":"integer","minimum":0,"maximum":9007199254740991},"receivedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"body":{"anyOf":[{"$ref":"#/components/schemas/StoredEmailBody"},{"type":"null"}]}},"required":["id","account","messageId","sender","recipient","subject","status","notes","labels","rawSize","receivedAt","createdAt","updatedAt","body"]},"EmailDetailResponse":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/EmailDetail"}},"required":["item"]},"UpdateEmailRequest":{"type":"object","properties":{"labels":{"maxItems":32,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"notes":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}]},"status":{"$ref":"#/components/schemas/EmailStatus"},"subject":{"anyOf":[{"type":"string","maxLength":998},{"type":"null"}]}}}}},"paths":{"/v1/emails":{"get":{"operationId":"listEmails","tags":["Emails"],"summary":"List captured emails","description":"Returns emails for the authenticated account, ordered from newest to oldest.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"Emails retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEmailsResponse"}}}},"400":{"description":"The query string did not pass validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"query","name":"limit","schema":{"default":25,"type":"integer","minimum":1,"maximum":100},"description":"Maximum number of emails to return."},{"in":"query","name":"offset","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"description":"Number of emails to skip before returning results."},{"in":"query","name":"recipient","schema":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"description":"Filter by recipient address."},{"in":"query","name":"sender","schema":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"description":"Filter by sender address."},{"in":"query","name":"status","schema":{"$ref":"#/components/schemas/EmailStatus"}},{"in":"query","name":"subject","schema":{"type":"string","minLength":1,"maxLength":255},"description":"Match emails whose subject contains this value."}]},"post":{"operationId":"createEmail","tags":["Emails"],"summary":"Create a captured email","description":"Stores a new email body and metadata for the authenticated account.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"201":{"description":"Email stored successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailResponse"}}}},"400":{"description":"The request body did not pass validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEmailRequest"}}}}}},"/v1/emails/{emailId}":{"get":{"operationId":"getEmail","tags":["Emails"],"summary":"Get an email by id","description":"Returns metadata and stored body content for a single captured email.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"Email retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDetailResponse"}}}},"400":{"description":"The route parameters did not pass validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested email was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"path","name":"emailId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"MailtestAPI email identifier."}]},"patch":{"operationId":"updateEmail","tags":["Emails"],"summary":"Update an email","description":"Updates mutable metadata for a captured email.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"200":{"description":"Email updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailResponse"}}}},"400":{"description":"The route parameters or request body did not pass validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested email was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"path","name":"emailId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"MailtestAPI email identifier."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEmailRequest"}}}}},"delete":{"operationId":"deleteEmail","tags":["Emails"],"summary":"Delete an email","description":"Deletes the email metadata record and its stored body.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"responses":{"204":{"description":"Email deleted successfully."},"400":{"description":"The route parameters did not pass validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested email was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"path","name":"emailId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"MailtestAPI email identifier."}]}}}}