{
	"openapi": "3.1.0",
	"info": {
		"title": "PostStack API",
		"version": "1.0",
		"summary": "European email API — send transactional and marketing email, manage contacts, domains, templates, broadcasts and webhooks.",
		"description": "The PostStack REST API. All requests require a Bearer token (API key `sk_live_…` / `sk_test_…`, or OAuth 2.0 access token `pat_…`). All traffic and data stay in the EU. See https://poststack.dev/docs for guides and SDKs.",
		"termsOfService": "https://poststack.dev/terms",
		"contact": {
			"name": "PostStack Support",
			"url": "https://poststack.dev/contact",
			"email": "support@poststack.dev"
		},
		"license": {
			"name": "Proprietary",
			"url": "https://poststack.dev/terms"
		}
	},
	"servers": [
		{
			"url": "https://api.poststack.dev",
			"description": "Production"
		}
	],
	"externalDocs": {
		"description": "PostStack docs",
		"url": "https://poststack.dev/docs"
	},
	"security": [{ "bearerApiKey": [] }, { "bearerOAuth": [] }],
	"tags": [
		{ "name": "Emails", "description": "Send and inspect individual emails." },
		{
			"name": "Domains",
			"description": "Add and verify sending domains (SPF / DKIM / DMARC)."
		},
		{ "name": "Contacts", "description": "Manage subscribers and custom properties." },
		{ "name": "Segments", "description": "Dynamic and manual audiences." },
		{ "name": "Broadcasts", "description": "Bulk campaigns with scheduling and analytics." },
		{
			"name": "Templates",
			"description": "Reusable email templates with {{variable}} placeholders."
		},
		{ "name": "Webhooks", "description": "Real-time event delivery with HMAC signatures." },
		{
			"name": "Suppressions",
			"description": "Bounce, complaint, unsubscribe suppression list."
		},
		{
			"name": "Subscription topics",
			"description": "Fine-grained email preferences per contact."
		},
		{ "name": "Mailboxes", "description": "Full IMAP/POP3 mailboxes (Pro+)." },
		{ "name": "API keys", "description": "Manage API keys." },
		{
			"name": "Contact properties",
			"description": "Custom contact attributes (string / number / date / boolean) for segmentation."
		},
		{
			"name": "Workflows",
			"description": "Automated email sequences triggered by contact events or schedules."
		},
		{
			"name": "Signup forms",
			"description": "Hosted contact-collection forms with custom fields and double-opt-in."
		},
		{
			"name": "Email validations",
			"description": "Pre-send email-address validation (syntax, MX, disposable, role)."
		},
		{
			"name": "Inbound emails",
			"description": "Receive emails on your domain via MX → webhook."
		}
	],
	"paths": {
		"/emails": {
			"post": {
				"tags": ["Emails"],
				"operationId": "sendEmail",
				"summary": "Send an email",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": { "$ref": "#/components/schemas/SendEmailInput" }
						}
					}
				},
				"responses": {
					"200": {
						"description": "Email accepted",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/SendEmailResponse" }
							}
						}
					},
					"400": { "$ref": "#/components/responses/ValidationError" },
					"401": { "$ref": "#/components/responses/Unauthorized" },
					"402": { "$ref": "#/components/responses/QuotaExceeded" },
					"429": { "$ref": "#/components/responses/RateLimited" }
				}
			},
			"get": {
				"tags": ["Emails"],
				"operationId": "listEmails",
				"summary": "List sent emails",
				"parameters": [
					{ "$ref": "#/components/parameters/Page" },
					{ "$ref": "#/components/parameters/Limit" },
					{
						"name": "status",
						"in": "query",
						"schema": {
							"type": "string",
							"enum": [
								"queued",
								"sending",
								"sent",
								"delivered",
								"bounced",
								"complained",
								"failed",
								"cancelled"
							]
						}
					},
					{ "name": "from", "in": "query", "schema": { "type": "string" } },
					{ "name": "to", "in": "query", "schema": { "type": "string" } },
					{ "name": "tag", "in": "query", "schema": { "type": "string" } }
				],
				"responses": {
					"200": {
						"description": "Paginated list",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/PaginatedEmailList"
								}
							}
						}
					},
					"401": { "$ref": "#/components/responses/Unauthorized" }
				}
			}
		},
		"/emails/batch": {
			"post": {
				"tags": ["Emails"],
				"operationId": "sendBatch",
				"summary": "Send up to 100 emails in one request",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": ["emails"],
								"properties": {
									"emails": {
										"type": "array",
										"minItems": 1,
										"maxItems": 100,
										"items": { "$ref": "#/components/schemas/SendEmailInput" }
									}
								}
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Batch accepted",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"data": {
											"type": "array",
											"items": {
												"$ref": "#/components/schemas/SendEmailResponse"
											}
										}
									}
								}
							}
						}
					}
				}
			}
		},
		"/emails/{id}": {
			"parameters": [{ "$ref": "#/components/parameters/EmailId" }],
			"get": {
				"tags": ["Emails"],
				"operationId": "getEmail",
				"summary": "Fetch one email",
				"responses": {
					"200": {
						"description": "Email detail",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/Email" }
							}
						}
					},
					"404": { "$ref": "#/components/responses/NotFound" }
				}
			},
			"patch": {
				"tags": ["Emails"],
				"operationId": "rescheduleEmail",
				"summary": "Reschedule a queued email",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": ["scheduled_at"],
								"properties": {
									"scheduled_at": { "type": "string", "format": "date-time" }
								}
							}
						}
					}
				},
				"responses": {
					"200": { "$ref": "#/components/responses/Success" }
				}
			}
		},
		"/emails/{id}/cancel": {
			"parameters": [{ "$ref": "#/components/parameters/EmailId" }],
			"post": {
				"tags": ["Emails"],
				"operationId": "cancelEmail",
				"summary": "Cancel a scheduled or queued email",
				"responses": {
					"200": { "$ref": "#/components/responses/Success" },
					"404": { "$ref": "#/components/responses/NotFound" }
				}
			}
		},
		"/emails/{id}/events": {
			"parameters": [{ "$ref": "#/components/parameters/EmailId" }],
			"get": {
				"tags": ["Emails"],
				"operationId": "getEmailEvents",
				"summary": "Timeline of events for one email",
				"responses": {
					"200": {
						"description": "Events",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"events": {
											"type": "array",
											"items": { "$ref": "#/components/schemas/EmailEvent" }
										}
									}
								}
							}
						}
					}
				}
			}
		},
		"/domains": {
			"get": {
				"tags": ["Domains"],
				"operationId": "listDomains",
				"summary": "List sending domains",
				"parameters": [
					{ "$ref": "#/components/parameters/Page" },
					{ "$ref": "#/components/parameters/Limit" }
				],
				"responses": {
					"200": {
						"description": "Paginated list",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/PaginatedDomainList"
								}
							}
						}
					}
				}
			},
			"post": {
				"tags": ["Domains"],
				"operationId": "createDomain",
				"summary": "Add a sending domain",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": ["name"],
								"properties": {
									"name": { "type": "string", "example": "mail.example.com" },
									"region": {
										"type": "string",
										"enum": ["eu-west-1"],
										"default": "eu-west-1",
										"description": "PostStack is EU-only. Only `eu-west-1` is available today."
									},
									"open_tracking": { "type": "boolean", "default": false },
									"click_tracking": { "type": "boolean", "default": false },
									"tls_mode": {
										"type": "string",
										"enum": ["opportunistic", "enforced"],
										"default": "opportunistic"
									}
								}
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Domain created",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/Domain" }
							}
						}
					}
				}
			}
		},
		"/domains/{id}": {
			"parameters": [{ "$ref": "#/components/parameters/DomainId" }],
			"get": {
				"tags": ["Domains"],
				"operationId": "getDomain",
				"summary": "Fetch a domain",
				"responses": {
					"200": {
						"description": "Domain detail",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/Domain" }
							}
						}
					}
				}
			},
			"patch": {
				"tags": ["Domains"],
				"operationId": "updateDomain",
				"summary": "Update a domain's tracking or TLS settings",
				"requestBody": {
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"open_tracking": { "type": "boolean" },
									"click_tracking": { "type": "boolean" },
									"tls_mode": {
										"type": "string",
										"enum": ["opportunistic", "enforced"]
									}
								}
							}
						}
					}
				},
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			},
			"delete": {
				"tags": ["Domains"],
				"operationId": "deleteDomain",
				"summary": "Delete a domain",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/domains/{id}/verify": {
			"parameters": [{ "$ref": "#/components/parameters/DomainId" }],
			"post": {
				"tags": ["Domains"],
				"operationId": "verifyDomain",
				"summary": "Trigger a DNS verification check for this domain",
				"responses": {
					"200": {
						"description": "Verification result",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/Domain" }
							}
						}
					}
				}
			}
		},
		"/contacts": {
			"get": {
				"tags": ["Contacts"],
				"operationId": "listContacts",
				"summary": "List contacts",
				"parameters": [
					{ "$ref": "#/components/parameters/Page" },
					{ "$ref": "#/components/parameters/Limit" },
					{ "name": "search", "in": "query", "schema": { "type": "string" } },
					{ "name": "segment_id", "in": "query", "schema": { "type": "string" } }
				],
				"responses": {
					"200": {
						"description": "Paginated list",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/PaginatedContactList" }
							}
						}
					}
				}
			},
			"post": {
				"tags": ["Contacts"],
				"operationId": "createContact",
				"summary": "Create a contact",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": { "$ref": "#/components/schemas/CreateContactInput" }
						}
					}
				},
				"responses": {
					"200": {
						"description": "Contact created",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"contact": { "$ref": "#/components/schemas/Contact" }
									}
								}
							}
						}
					}
				}
			}
		},
		"/contacts/{id}": {
			"parameters": [{ "$ref": "#/components/parameters/ContactId" }],
			"get": {
				"tags": ["Contacts"],
				"operationId": "getContact",
				"summary": "Fetch a contact",
				"responses": {
					"200": {
						"description": "Contact",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"contact": { "$ref": "#/components/schemas/Contact" }
									}
								}
							}
						}
					}
				}
			},
			"patch": {
				"tags": ["Contacts"],
				"operationId": "updateContact",
				"summary": "Update a contact",
				"requestBody": {
					"content": {
						"application/json": {
							"schema": { "$ref": "#/components/schemas/UpdateContactInput" }
						}
					}
				},
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			},
			"delete": {
				"tags": ["Contacts"],
				"operationId": "deleteContact",
				"summary": "Delete a contact",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/contacts/import": {
			"post": {
				"tags": ["Contacts"],
				"operationId": "importContacts",
				"summary": "Import a CSV list of contacts",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": ["csv"],
								"properties": {
									"csv": {
										"type": "string",
										"description": "CSV body with `email` header; optional `first_name`, `last_name`, `unsubscribed`."
									},
									"segment_id": { "type": "string" }
								}
							}
						}
					}
				},
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/broadcasts": {
			"get": {
				"tags": ["Broadcasts"],
				"operationId": "listBroadcasts",
				"summary": "List broadcasts",
				"parameters": [
					{ "$ref": "#/components/parameters/Page" },
					{ "$ref": "#/components/parameters/Limit" }
				],
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			},
			"post": {
				"tags": ["Broadcasts"],
				"operationId": "createBroadcast",
				"summary": "Create a broadcast",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": { "$ref": "#/components/schemas/CreateBroadcastInput" }
						}
					}
				},
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/broadcasts/{id}/send": {
			"parameters": [{ "$ref": "#/components/parameters/BroadcastId" }],
			"post": {
				"tags": ["Broadcasts"],
				"operationId": "sendBroadcast",
				"summary": "Start sending a broadcast",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/broadcasts/{id}/cancel": {
			"parameters": [{ "$ref": "#/components/parameters/BroadcastId" }],
			"post": {
				"tags": ["Broadcasts"],
				"operationId": "cancelBroadcast",
				"summary": "Cancel an in-flight broadcast",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/templates": {
			"get": {
				"tags": ["Templates"],
				"operationId": "listTemplates",
				"summary": "List templates",
				"parameters": [
					{ "$ref": "#/components/parameters/Page" },
					{ "$ref": "#/components/parameters/Limit" }
				],
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			},
			"post": {
				"tags": ["Templates"],
				"operationId": "createTemplate",
				"summary": "Create a template",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": { "$ref": "#/components/schemas/CreateTemplateInput" }
						}
					}
				},
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/templates/{id}": {
			"parameters": [{ "$ref": "#/components/parameters/TemplateId" }],
			"get": {
				"tags": ["Templates"],
				"operationId": "getTemplate",
				"summary": "Fetch a template",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			},
			"patch": {
				"tags": ["Templates"],
				"operationId": "updateTemplate",
				"summary": "Update a template (creates a new version)",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			},
			"delete": {
				"tags": ["Templates"],
				"operationId": "deleteTemplate",
				"summary": "Delete a template",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/segments": {
			"get": {
				"tags": ["Segments"],
				"operationId": "listSegments",
				"summary": "List segments",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			},
			"post": {
				"tags": ["Segments"],
				"operationId": "createSegment",
				"summary": "Create a manual segment",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": ["name"],
								"properties": { "name": { "type": "string" } }
							}
						}
					}
				},
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/segments/{id}/contacts": {
			"parameters": [{ "$ref": "#/components/parameters/SegmentId" }],
			"post": {
				"tags": ["Segments"],
				"operationId": "addContactsToSegment",
				"summary": "Add contacts to a segment",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": ["contact_ids"],
								"properties": {
									"contact_ids": {
										"type": "array",
										"items": { "type": "string" }
									}
								}
							}
						}
					}
				},
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/webhooks": {
			"get": {
				"tags": ["Webhooks"],
				"operationId": "listWebhooks",
				"summary": "List webhooks",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			},
			"post": {
				"tags": ["Webhooks"],
				"operationId": "createWebhook",
				"summary": "Create a webhook subscription",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": { "$ref": "#/components/schemas/CreateWebhookInput" }
						}
					}
				},
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/webhooks/{id}": {
			"parameters": [{ "$ref": "#/components/parameters/WebhookId" }],
			"patch": {
				"tags": ["Webhooks"],
				"operationId": "updateWebhook",
				"summary": "Update a webhook",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			},
			"delete": {
				"tags": ["Webhooks"],
				"operationId": "deleteWebhook",
				"summary": "Delete a webhook",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/webhooks/{id}/test": {
			"parameters": [{ "$ref": "#/components/parameters/WebhookId" }],
			"post": {
				"tags": ["Webhooks"],
				"operationId": "testWebhook",
				"summary": "Send a test event to the webhook URL",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/suppressions": {
			"get": {
				"tags": ["Suppressions"],
				"operationId": "listSuppressions",
				"summary": "List suppressed addresses",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			},
			"post": {
				"tags": ["Suppressions"],
				"operationId": "addSuppression",
				"summary": "Add an address to the suppression list",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": ["email", "reason"],
								"properties": {
									"email": { "type": "string", "format": "email" },
									"reason": {
										"type": "string",
										"enum": ["bounce", "complaint", "manual"]
									}
								}
							}
						}
					}
				},
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/subscription-topics": {
			"get": {
				"tags": ["Subscription topics"],
				"operationId": "listTopics",
				"summary": "List subscription topics",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			},
			"post": {
				"tags": ["Subscription topics"],
				"operationId": "createTopic",
				"summary": "Create a subscription topic",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/mailboxes": {
			"get": {
				"tags": ["Mailboxes"],
				"operationId": "listMailboxes",
				"summary": "List mailboxes",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			},
			"post": {
				"tags": ["Mailboxes"],
				"operationId": "createMailbox",
				"summary": "Create a mailbox",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/api-keys": {
			"get": {
				"tags": ["API keys"],
				"operationId": "listApiKeys",
				"summary": "List API keys",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			},
			"post": {
				"tags": ["API keys"],
				"operationId": "createApiKey",
				"summary": "Create an API key",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": ["name", "permission"],
								"properties": {
									"name": { "type": "string" },
									"permission": {
										"type": "string",
										"enum": ["full_access", "sending_access"]
									},
									"mode": {
										"type": "string",
										"enum": ["live", "test"],
										"default": "live"
									}
								}
							}
						}
					}
				},
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/contact-properties": {
			"get": {
				"tags": ["Contact properties"],
				"operationId": "listContactProperties",
				"summary": "List contact properties",
				"description": "Custom attributes (string/number/date/boolean) attached to contacts and usable in segment rules.",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			},
			"post": {
				"tags": ["Contact properties"],
				"operationId": "createContactProperty",
				"summary": "Create a contact property",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": ["name", "type"],
								"properties": {
									"name": { "type": "string" },
									"type": {
										"type": "string",
										"enum": ["string", "number", "date", "boolean"]
									}
								}
							}
						}
					}
				},
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/workflows": {
			"get": {
				"tags": ["Workflows"],
				"operationId": "listWorkflows",
				"summary": "List workflows",
				"description": "Automated email sequences. Triggered by contact events (subscribed, tag added) or schedules.",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/workflows/{id}": {
			"get": {
				"tags": ["Workflows"],
				"operationId": "getWorkflow",
				"summary": "Get a workflow",
				"parameters": [{ "$ref": "#/components/parameters/PublicId" }],
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/signup-forms": {
			"get": {
				"tags": ["Signup forms"],
				"operationId": "listSignupForms",
				"summary": "List signup forms",
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/signup-forms/{id}/submit": {
			"post": {
				"tags": ["Signup forms"],
				"operationId": "submitSignupForm",
				"summary": "Submit a signup form (public, unauthenticated)",
				"description": "Public endpoint — no API key required. Honeypot + rate-limited. Creates a contact and triggers double-opt-in if configured.",
				"security": [],
				"parameters": [{ "$ref": "#/components/parameters/PublicId" }],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": ["email"],
								"properties": {
									"email": { "type": "string", "format": "email" },
									"properties": { "type": "object", "additionalProperties": true }
								}
							}
						}
					}
				},
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/email-validations": {
			"post": {
				"tags": ["Email validations"],
				"operationId": "validateEmail",
				"summary": "Validate an email address",
				"description": "Syntax, MX, role-account, and disposable-domain checks. Use before sending to reduce bounce rate.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": ["email"],
								"properties": {
									"email": { "type": "string", "format": "email" }
								}
							}
						}
					}
				},
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/inbound": {
			"get": {
				"tags": ["Inbound emails"],
				"operationId": "listInboundEmails",
				"summary": "List received inbound emails",
				"description": "Inbound mail received via MX records on inbound-enabled domains. IDs are numeric. Real-time delivery via webhook events.",
				"parameters": [
					{ "$ref": "#/components/parameters/Page" },
					{ "$ref": "#/components/parameters/Limit" },
					{
						"name": "domain",
						"in": "query",
						"required": false,
						"schema": { "type": "string" },
						"description": "Restrict results to a single verified domain (by name)."
					}
				],
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		},
		"/inbound/{id}": {
			"get": {
				"tags": ["Inbound emails"],
				"operationId": "getInboundEmail",
				"summary": "Get an inbound email",
				"parameters": [{ "$ref": "#/components/parameters/InboundId" }],
				"responses": { "200": { "$ref": "#/components/responses/Success" } }
			}
		}
	},
	"components": {
		"securitySchemes": {
			"bearerApiKey": {
				"type": "http",
				"scheme": "bearer",
				"bearerFormat": "PostStack API key (sk_live_… / sk_test_…)"
			},
			"bearerOAuth": {
				"type": "oauth2",
				"description": "OAuth 2.0 with PKCE. Dark-launched behind OAUTH_AS_ENABLED; when live, discover at /.well-known/oauth-authorization-server.",
				"flows": {
					"authorizationCode": {
						"authorizationUrl": "https://poststack.dev/oauth/authorize",
						"tokenUrl": "https://poststack.dev/oauth/token",
						"refreshUrl": "https://poststack.dev/oauth/token",
						"scopes": {
							"email:send": "Send emails on your behalf",
							"email:read": "Read email history, analytics, and suppressions",
							"domains:manage": "Create, verify, and delete sending domains",
							"domains:read": "View sending domains and their verification status",
							"mailboxes:manage": "Create and manage IMAP/POP3 mailboxes",
							"api-keys:manage": "Create, rotate, and revoke API keys",
							"mcp:read": "Use read-only MCP tools",
							"mcp:send": "Use MCP tools that send email",
							"mcp:admin": "Use MCP tools that mutate account state"
						}
					}
				}
			}
		},
		"parameters": {
			"Page": {
				"name": "page",
				"in": "query",
				"schema": { "type": "integer", "minimum": 1, "default": 1 }
			},
			"Limit": {
				"name": "limit",
				"in": "query",
				"schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }
			},
			"EmailId": {
				"name": "id",
				"in": "path",
				"required": true,
				"schema": { "type": "string" },
				"description": "Email public ID (starts with `em_`)"
			},
			"PublicId": {
				"name": "id",
				"in": "path",
				"required": true,
				"schema": { "type": "string" },
				"description": "Resource public ID (typed prefix like `wf_`, `sf_`)."
			},
			"InboundId": {
				"name": "id",
				"in": "path",
				"required": true,
				"schema": { "type": "integer" },
				"description": "Inbound email numeric ID (e.g. `7`)."
			},
			"DomainId": {
				"name": "id",
				"in": "path",
				"required": true,
				"schema": { "type": "string" }
			},
			"ContactId": {
				"name": "id",
				"in": "path",
				"required": true,
				"schema": { "type": "string" }
			},
			"BroadcastId": {
				"name": "id",
				"in": "path",
				"required": true,
				"schema": { "type": "string" }
			},
			"TemplateId": {
				"name": "id",
				"in": "path",
				"required": true,
				"schema": { "type": "string" }
			},
			"SegmentId": {
				"name": "id",
				"in": "path",
				"required": true,
				"schema": { "type": "string" }
			},
			"WebhookId": {
				"name": "id",
				"in": "path",
				"required": true,
				"schema": { "type": "string" }
			}
		},
		"responses": {
			"Success": {
				"description": "OK",
				"content": {
					"application/json": {
						"schema": {
							"type": "object",
							"properties": { "success": { "type": "boolean", "example": true } }
						}
					}
				}
			},
			"Unauthorized": {
				"description": "Missing or invalid API key",
				"content": {
					"application/json": {
						"schema": { "$ref": "#/components/schemas/Error" }
					}
				}
			},
			"ValidationError": {
				"description": "Request body or query params failed validation",
				"content": {
					"application/json": {
						"schema": { "$ref": "#/components/schemas/Error" }
					}
				}
			},
			"NotFound": {
				"description": "Resource not found",
				"content": {
					"application/json": {
						"schema": { "$ref": "#/components/schemas/Error" }
					}
				}
			},
			"QuotaExceeded": {
				"description": "Plan quota exhausted (monthly send cap / domain cap / mailbox cap)",
				"content": {
					"application/json": {
						"schema": { "$ref": "#/components/schemas/Error" }
					}
				}
			},
			"RateLimited": {
				"description": "Too many requests — back off and retry",
				"content": {
					"application/json": {
						"schema": { "$ref": "#/components/schemas/Error" }
					}
				}
			}
		},
		"schemas": {
			"Error": {
				"type": "object",
				"required": ["error"],
				"properties": {
					"error": { "type": "string" }
				}
			},
			"SendEmailInput": {
				"type": "object",
				"required": ["from", "to"],
				"properties": {
					"from": {
						"type": "string",
						"description": "`Name <email@verified-domain>` or just `email@verified-domain`. The domain must be verified in your account.",
						"example": "Acme <noreply@acme.com>"
					},
					"to": {
						"type": "array",
						"items": { "type": "string", "format": "email" },
						"maxItems": 50
					},
					"cc": {
						"type": "array",
						"items": { "type": "string", "format": "email" },
						"maxItems": 50
					},
					"bcc": {
						"type": "array",
						"items": { "type": "string", "format": "email" },
						"maxItems": 50
					},
					"reply_to": { "type": "string", "format": "email" },
					"subject": { "type": "string" },
					"html": { "type": "string" },
					"text": { "type": "string" },
					"headers": {
						"type": "object",
						"additionalProperties": { "type": "string" }
					},
					"tags": { "type": "array", "items": { "type": "string" } },
					"attachments": {
						"type": "array",
						"items": { "$ref": "#/components/schemas/Attachment" }
					},
					"idempotency_key": {
						"type": "string",
						"description": "Deduplicates sends for 24h."
					},
					"scheduled_at": { "type": "string", "format": "date-time" },
					"template_id": { "type": "string" },
					"variables": {
						"type": "object",
						"additionalProperties": { "type": "string" }
					}
				}
			},
			"Attachment": {
				"type": "object",
				"required": ["filename", "content"],
				"properties": {
					"filename": { "type": "string" },
					"content": { "type": "string", "description": "base64-encoded file contents" },
					"content_type": {
						"type": "string",
						"description": "Defaults to inferred MIME type"
					}
				}
			},
			"SendEmailResponse": {
				"type": "object",
				"required": ["id"],
				"properties": {
					"id": { "type": "string", "description": "Email public ID (starts with `em_`)" }
				}
			},
			"Email": {
				"type": "object",
				"required": ["id", "status", "created_at"],
				"properties": {
					"id": { "type": "string" },
					"from": { "type": "string" },
					"to": { "type": "array", "items": { "type": "string" } },
					"subject": { "type": "string" },
					"status": {
						"type": "string",
						"enum": [
							"queued",
							"sending",
							"sent",
							"delivered",
							"bounced",
							"complained",
							"failed",
							"cancelled"
						]
					},
					"tags": { "type": "array", "items": { "type": "string" } },
					"created_at": { "type": "string", "format": "date-time" },
					"scheduled_at": { "type": "string", "format": "date-time", "nullable": true },
					"delivered_at": { "type": "string", "format": "date-time", "nullable": true }
				}
			},
			"EmailEvent": {
				"type": "object",
				"properties": {
					"type": {
						"type": "string",
						"enum": [
							"queued",
							"sending",
							"sent",
							"delivered",
							"bounced",
							"complained",
							"opened",
							"clicked",
							"failed",
							"cancelled"
						]
					},
					"timestamp": { "type": "string", "format": "date-time" },
					"data": { "type": "object", "additionalProperties": true }
				}
			},
			"PaginatedEmailList": {
				"type": "object",
				"properties": {
					"data": { "type": "array", "items": { "$ref": "#/components/schemas/Email" } },
					"pagination": { "$ref": "#/components/schemas/Pagination" }
				}
			},
			"Domain": {
				"type": "object",
				"properties": {
					"id": { "type": "string" },
					"name": { "type": "string" },
					"status": {
						"type": "string",
						"enum": ["pending", "verified", "failed"]
					},
					"region": { "type": "string", "enum": ["eu-west-1"] },
					"open_tracking": { "type": "boolean" },
					"click_tracking": { "type": "boolean" },
					"tls_mode": { "type": "string", "enum": ["opportunistic", "enforced"] },
					"dns_records": {
						"type": "array",
						"items": {
							"type": "object",
							"properties": {
								"type": { "type": "string", "enum": ["TXT", "MX", "CNAME"] },
								"name": { "type": "string" },
								"value": { "type": "string" },
								"status": {
									"type": "string",
									"enum": ["pending", "verified", "failed"]
								}
							}
						}
					},
					"created_at": { "type": "string", "format": "date-time" }
				}
			},
			"PaginatedDomainList": {
				"type": "object",
				"properties": {
					"data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } },
					"pagination": { "$ref": "#/components/schemas/Pagination" }
				}
			},
			"Contact": {
				"type": "object",
				"properties": {
					"id": { "type": "string" },
					"email": { "type": "string", "format": "email" },
					"first_name": { "type": "string", "nullable": true },
					"last_name": { "type": "string", "nullable": true },
					"unsubscribed": { "type": "boolean" },
					"properties": { "type": "object", "additionalProperties": true },
					"created_at": { "type": "string", "format": "date-time" }
				}
			},
			"CreateContactInput": {
				"type": "object",
				"required": ["email"],
				"properties": {
					"email": { "type": "string", "format": "email" },
					"first_name": { "type": "string" },
					"last_name": { "type": "string" },
					"unsubscribed": { "type": "boolean", "default": false },
					"properties": { "type": "object", "additionalProperties": true }
				}
			},
			"UpdateContactInput": {
				"type": "object",
				"properties": {
					"first_name": { "type": "string" },
					"last_name": { "type": "string" },
					"unsubscribed": { "type": "boolean" },
					"properties": { "type": "object", "additionalProperties": true }
				}
			},
			"PaginatedContactList": {
				"type": "object",
				"properties": {
					"data": {
						"type": "array",
						"items": { "$ref": "#/components/schemas/Contact" }
					},
					"pagination": { "$ref": "#/components/schemas/Pagination" }
				}
			},
			"CreateTemplateInput": {
				"type": "object",
				"required": ["name", "subject", "html"],
				"properties": {
					"name": { "type": "string" },
					"subject": { "type": "string" },
					"html": { "type": "string" },
					"text": { "type": "string" },
					"variables": { "type": "array", "items": { "type": "string" } },
					"builder_type": {
						"type": "string",
						"enum": ["html", "visual"],
						"description": "Authoring mode. `visual` stores the block tree in builder_blocks; PostStack compiles it to HTML on save."
					},
					"builder_blocks": {
						"type": "array",
						"description": "Block tree when builder_type is `visual`. Ignored otherwise.",
						"items": { "type": "object", "additionalProperties": true }
					}
				}
			},
			"CreateBroadcastInput": {
				"type": "object",
				"required": ["name", "from", "subject", "html"],
				"properties": {
					"name": { "type": "string" },
					"from": { "type": "string" },
					"subject": { "type": "string" },
					"html": { "type": "string" },
					"text": { "type": "string" },
					"segment_ids": { "type": "array", "items": { "type": "string" } },
					"topic_id": { "type": "string" },
					"scheduled_at": { "type": "string", "format": "date-time" },
					"ab_test": {
						"type": "object",
						"description": "Enable A/B testing. Each variant is sent to a share of the audience; the winner (highest open rate) is picked after test_duration_minutes and sent to the rest.",
						"required": ["variants", "test_duration_minutes"],
						"properties": {
							"variants": {
								"type": "array",
								"minItems": 2,
								"maxItems": 5,
								"items": {
									"type": "object",
									"required": ["name", "subject", "weight"],
									"properties": {
										"name": { "type": "string" },
										"subject": { "type": "string" },
										"html": { "type": "string" },
										"text": { "type": "string" },
										"weight": {
											"type": "integer",
											"minimum": 1,
											"maximum": 100
										}
									}
								}
							},
							"test_duration_minutes": { "type": "integer", "minimum": 5 }
						}
					}
				}
			},
			"CreateWebhookInput": {
				"type": "object",
				"required": ["url", "events"],
				"properties": {
					"url": { "type": "string", "format": "uri" },
					"events": {
						"type": "array",
						"items": {
							"type": "string",
							"enum": [
								"email.sent",
								"email.delivered",
								"email.bounced",
								"email.complained",
								"email.opened",
								"email.clicked",
								"email.failed",
								"contact.created",
								"contact.updated",
								"contact.deleted",
								"broadcast.sent"
							]
						}
					}
				}
			},
			"Pagination": {
				"type": "object",
				"properties": {
					"page": { "type": "integer" },
					"limit": { "type": "integer" },
					"total": { "type": "integer" },
					"totalPages": { "type": "integer" }
				}
			}
		}
	}
}