{ "openapi": "3.1.0", "info": { "title": "Migma.ai API (v1)", "description": "API for managing brands, contacts, email generation, sending, and integrations.", "license": { "name": "MIT" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.migma.ai", "description": "Production" } ], "security": [ { "apiKeyAuth": [] } ], "tags": [ { "name": "Projects/Brands", "description": "Manage projects (brands) and import from websites" }, { "name": "Contacts", "description": "Manage your contacts, segments, tags, and topics" }, { "name": "Segments", "description": "Create and manage dynamic contact segments" }, { "name": "Tags", "description": "Organize contacts with tags" }, { "name": "Topics", "description": "Manage subscription topics and preferences" }, { "name": "Emails", "description": "Generate, send, and export emails" }, { "name": "Email Validation", "description": "Validate email content for compatibility and deliverability" }, { "name": "Email Previews", "description": "Preview emails across devices and email clients" }, { "name": "Domains", "description": "Manage sending domains and verification" }, { "name": "Webhooks", "description": "Manage webhook endpoints for real-time event notifications" }, { "name": "Events", "description": "Record customer events and conversions" }, { "name": "Integrations", "description": "Third-party platform integrations" }, { "name": "Campaigns", "description": "Create, schedule, send, and manage email campaigns" }, { "name": "Billing", "description": "View your plan and credits and create billing links" }, { "name": "Project Editing", "description": "Edit project assets, logos, images, and knowledge base entries" } ], "paths": { "/v1/projects": { "get": { "tags": [ "Projects/Brands" ], "summary": "List Projects", "description": "List projects for the authenticated user with basic information only. Use GET /v1/projects/{projectId} to get full project details.", "operationId": "ListProjects", "parameters": [ { "name": "limit", "in": "query", "description": "The maximum number of results to return (max 100)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20 } }, { "name": "offset", "in": "query", "description": "The number of items to skip before starting to collect the result set", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "status", "in": "query", "description": "Filter by project status (pending|processing|active|error)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Projects list response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseProjectsList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.projects.list();" } ] } }, "/v1/projects/{projectId}": { "get": { "tags": [ "Projects/Brands" ], "summary": "Get Project Details", "description": "Get complete project details by ID, including branding information, colors, typography, and all project data.", "operationId": "GetProjectDetails", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "responses": { "200": { "description": "Project response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseProject" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.projects.get('PROJECT_ID');" } ] } }, "/v1/projects/{projectId}/field-catalog": { "get": { "tags": [ "Projects/Brands" ], "summary": "Get Project Field Catalog", "description": "Returns subscriber field metadata for the project: which fields exist, how often each is populated (fillRate), example values, and whether the field is auto-filled at send time. Powers variable pickers, persona prefill, and template-coverage UIs. Optionally scope the result to a specific segment or tag.", "operationId": "GetProjectFieldCatalog", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } }, { "name": "segmentId", "in": "query", "description": "Restrict the catalog to subscribers in this segment.", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } }, { "name": "tag", "in": "query", "description": "Restrict the catalog to subscribers with this tag id.", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "responses": { "200": { "description": "Field catalog response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseFieldCatalog" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.projects.fieldCatalog('PROJECT_ID');\n\n// Scope to a segment or tag:\n// await migma.projects.fieldCatalog('PROJECT_ID', { segmentId: 'SEGMENT_ID' });\n// await migma.projects.fieldCatalog('PROJECT_ID', { tag: 'TAG_ID' });" } ] } }, "/v1/projects/import": { "post": { "tags": [ "Projects/Brands" ], "summary": "Import Project", "description": "Import a brand project from one or more website URLs. Optionally include logo URLs to skip AI logo extraction. Requires API key with project:write.", "operationId": "ImportProject", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportProjectRequest" } } } }, "responses": { "200": { "description": "Import started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseImportStarted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.projects.import({\n urls: ['https://yourbrand.com']\n});\n\n// Or wait for completion:\n// const result = await migma.projects.importAndWait({ urls: ['https://yourbrand.com'] });" } ] } }, "/v1/projects/import/{projectId}/status": { "get": { "tags": [ "Projects/Brands" ], "summary": "Get Import Status", "description": "Check the status of a project import.", "operationId": "GetImportStatus", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "responses": { "200": { "description": "Import status response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseImportStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.projects.getImportStatus('PROJECT_ID');" } ] } }, "/v1/projects/import/{projectId}/retry": { "post": { "tags": [ "Projects/Brands" ], "summary": "Retry Import", "description": "Retry a failed or stuck import for the given project. Requires API key with project:write.", "operationId": "RetryImport", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "responses": { "200": { "description": "Retry initiated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseImportRetry" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.projects.retryImport('PROJECT_ID');" } ] } }, "/v1/projects/emails": { "get": { "tags": [ "Emails" ], "summary": "List Emails", "description": "List emails (conversations) for a project. Returns lightweight metadata including subject, status, and screenshot URL.", "operationId": "ListEmails", "parameters": [ { "name": "projectId", "in": "query", "description": "Project ID to list emails for", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } }, { "name": "limit", "in": "query", "description": "Maximum number of results (1-100)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "format": "int32", "default": 1, "minimum": 1 } }, { "name": "status", "in": "query", "description": "Filter by generation status", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] } }, { "name": "search", "in": "query", "description": "Search by title or subject", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of emails", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ListEmailsData" } } } ] } } } }, "400": { "description": "Validation error" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden \u2014 no access to this project" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.emails.list({\n projectId: 'PROJECT_ID',\n limit: 10,\n status: 'completed'\n});" }, { "lang": "bash", "label": "CLI", "source": "migma emails list --project PROJECT_ID --limit 10 --status completed --json" } ] } }, "/v1/projects/emails/generate": { "post": { "tags": [ "Emails" ], "summary": "Generate Email (Async)", "description": "Generate one email or a multi-email series for a project using its brand context and optional images. Requires API key with email:write. Provide count (1-12) to request a specific series length, or omit it to infer from the prompt. Returns immediately with a conversationId and pending status. Use GET /v1/projects/emails/{conversationId}/status to retrieve production HTML, screenshots, and per-email IDs.", "operationId": "GenerateEmail", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateEmailRequest" } } } }, "responses": { "200": { "description": "Email generation started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseGenerateEmail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.emails.generate({\n projectId: 'PROJECT_ID',\n prompt: 'Create a three-email onboarding series',\n count: 3,\n languages: ['en']\n});\n\n// Poll /status or use generateAndWait() to get result.emails[]." } ] } }, "/v1/projects/emails/import-html": { "post": { "tags": [ "Emails" ], "summary": "Import HTML Email (Async)", "description": "Convert existing HTML or .eml into editable Migma emails using the same HTML to Email path as Create. Requires API key with email:write. Provide html for one file or htmls (1-12). Optional instruction describes keep-as-is vs apply-brand. Returns immediately with a conversationId and pending status. Use GET /v1/projects/emails/{conversationId}/status to retrieve production HTML, screenshots, and per-email IDs. Do not send HTML to generate.", "operationId": "ImportHtmlEmail", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportHtmlEmailRequest" } } } }, "responses": { "200": { "description": "HTML import started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseGenerateEmail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.emails.importHtml({\n projectId: 'PROJECT_ID',\n html: 'Welcome',\n name: 'welcome.html',\n instruction: 'Keep this exactly as-is'\n});\n\n// Poll /status or use importHtmlAndWait() to get result.emails[]." } ] } }, "/v1/projects/emails/{conversationId}/status": { "get": { "tags": [ "Emails" ], "summary": "Get Email Generation Status", "description": "Check email generation status. When completed, returns primary email HTML plus result.emails[] for every generated email, including emailId, subject, HTML, screenshot URL, and series order.", "operationId": "GetEmailGenerationStatus", "parameters": [ { "name": "conversationId", "in": "path", "description": "The conversation ID returned from the generate endpoint", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Email status retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseEmailStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data } = await migma.emails.getGenerationStatus('CONVERSATION_ID');\n\nfor (const email of data.result?.emails || []) {\n console.log(email.emailId, email.subject, email.html, email.screenshotUrl);\n}" } ] } }, "/v1/emails/test/send": { "post": { "tags": [ "Emails" ], "summary": "Send Test Email", "description": "Send a test email to one address. Use emailId for a specific generated email, especially emails inside a series. conversationId remains supported for single-email conversations. Requires API key with email:send permission.", "operationId": "SendTestEmail", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendTestEmailRequest" } } } }, "responses": { "200": { "description": "Test email sent successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTestEmailSent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.emails.sendTest({\n emailId: 'EMAIL_ID',\n to: 'test@example.com'\n});" } ] } }, "/v1/emails/validate/compatibility": { "post": { "tags": [ "Email Validation" ], "summary": "Check Email Compatibility", "description": "Test email HTML on major webmail, desktop, and mobile clients and return a compatibility report. Flags rendering issues in Gmail, Outlook, Apple Mail, and other supported clients.", "operationId": "CheckEmailCompatibility", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "html" ], "properties": { "html": { "type": "string", "description": "Email HTML content to validate" }, "clients": { "type": "array", "items": { "type": "string" }, "description": "Specific email client IDs to test (optional; defaults to the standard client set)" } } } } } }, "responses": { "200": { "description": "Compatibility check completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "clientIssues": { "type": "array", "description": "Issues found for each email client", "items": { "type": "object", "properties": { "client": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "object" } } } } }, "summary": { "type": "object", "properties": { "totalErrors": { "type": "integer" }, "totalWarnings": { "type": "integer" }, "compatibilityScore": { "type": "integer", "description": "Overall compatibility score (0-100)" } } }, "supportedClients": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "properties": { "processingTime": { "type": "integer" }, "clientsTested": { "type": "integer" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.validation.compatibility({\n html: '...'\n});" } ] } }, "/v1/emails/validate/links": { "post": { "tags": [ "Email Validation" ], "summary": "Analyze Email Links", "description": "Check all links in email HTML for validity and responsiveness. Identifies broken links, slow-loading resources, and unreachable URLs.", "operationId": "AnalyzeEmailLinks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "html" ], "properties": { "html": { "type": "string", "description": "Email HTML content containing links" }, "timeout": { "type": "integer", "default": 10000, "minimum": 1000, "maximum": 30000, "description": "Timeout per link in milliseconds" }, "followRedirects": { "type": "boolean", "default": true, "description": "Follow HTTP redirects when checking links" } } } } } }, "responses": { "200": { "description": "Link analysis completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "totalLinks": { "type": "integer" }, "checkedLinks": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "integer" }, "statusText": { "type": "string" }, "responseTime": { "type": "integer" }, "error": { "type": "string" } } } }, "summary": { "type": "object", "properties": { "workingLinks": { "type": "integer" }, "brokenLinks": { "type": "integer" }, "unreachableLinks": { "type": "integer" }, "averageResponseTime": { "type": "integer" } } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "properties": { "processingTime": { "type": "integer" }, "linksChecked": { "type": "integer" }, "linksSkipped": { "type": "integer" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.validation.links({\n html: '...'\n});" } ] } }, "/v1/emails/validate/spelling": { "post": { "tags": [ "Email Validation" ], "summary": "Check Spelling & Grammar", "description": "AI-powered spell checking, grammar analysis, and content quality assessment for email content.", "operationId": "CheckEmailSpelling", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "html" ], "properties": { "html": { "type": "string", "description": "Email HTML content to check" }, "languages": { "type": "array", "items": { "type": "string" }, "description": "Languages to check (auto-detected if not provided)" }, "checkGrammar": { "type": "boolean", "default": true, "description": "Include grammar checking" } } } } } }, "responses": { "200": { "description": "Spelling check completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "totalWords": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "context": { "type": "string" }, "type": { "type": "string" } } } }, "summary": { "type": "object", "properties": { "totalErrors": { "type": "integer" }, "uniqueErrors": { "type": "integer" } } }, "metadata": { "type": "object", "properties": { "processingTime": { "type": "integer" }, "aiModel": { "type": "string" }, "tokensUsed": { "type": "integer" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.validation.spelling({\n html: '...'\n});" } ] } }, "/v1/emails/validate/deliverability": { "post": { "tags": [ "Email Validation" ], "summary": "Analyze Email Deliverability", "description": "Predict email deliverability and inbox placement (Inbox/Promotions/Spam) based on content analysis.", "operationId": "AnalyzeEmailDeliverability", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "html" ], "properties": { "html": { "type": "string", "description": "Email HTML content to analyze" }, "subject": { "type": "string", "description": "Email subject line" }, "fromName": { "type": "string", "description": "Sender name" }, "fromEmail": { "type": "string", "format": "email", "description": "Sender email address" } } } } } }, "responses": { "200": { "description": "Deliverability analysis completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "prediction": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "inbox", "promotions", "spam" ] }, "confidence": { "type": "integer" }, "score": { "type": "integer" }, "reasoning": { "type": "string" } } }, "contentSignals": { "type": "object", "properties": { "promotional": { "type": "array", "items": { "type": "string" } }, "transactional": { "type": "array", "items": { "type": "string" } }, "spam": { "type": "array", "items": { "type": "string" } }, "engagement": { "type": "array", "items": { "type": "string" } } } }, "spamScore": { "type": "object", "properties": { "score": { "type": "number" }, "triggers": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } } } }, "recommendations": { "type": "object", "properties": { "critical": { "type": "array", "items": { "type": "string" } }, "important": { "type": "array", "items": { "type": "string" } }, "suggested": { "type": "array", "items": { "type": "string" } } } }, "metadata": { "type": "object", "properties": { "processingTime": { "type": "integer" }, "analysisType": { "type": "string" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.validation.deliverability({\n html: '...',\n subject: 'My Email Subject'\n});" } ] } }, "/v1/emails/validate/all": { "post": { "tags": [ "Email Validation" ], "summary": "Run All Validation Checks", "description": "Run all validation checks (compatibility, links, spelling, deliverability) in a single request for comprehensive email analysis.", "operationId": "ValidateAllEmail", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "html" ], "properties": { "html": { "type": "string", "description": "Email HTML content to validate" }, "subject": { "type": "string", "description": "Email subject line" }, "options": { "type": "object", "properties": { "checkCompatibility": { "type": "boolean", "default": true }, "checkLinks": { "type": "boolean", "default": true }, "checkSpelling": { "type": "boolean", "default": true }, "checkDeliverability": { "type": "boolean", "default": true }, "clients": { "type": "array", "items": { "type": "string" } }, "languages": { "type": "array", "items": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "All validations completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "overallScore": { "type": "integer" }, "compatibility": { "type": "object" }, "linkAnalysis": { "type": "object" }, "spelling": { "type": "object" }, "deliverability": { "type": "object" }, "summary": { "type": "object", "properties": { "criticalIssues": { "type": "integer" }, "warnings": { "type": "integer" }, "passed": { "type": "array", "items": { "type": "string" } }, "failed": { "type": "array", "items": { "type": "string" } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.validation.all({\n html: '...',\n subject: 'My Email Subject'\n});" } ] } }, "/v1/emails/previews": { "post": { "tags": [ "Email Previews" ], "summary": "Create Email Preview", "description": "Generate email previews from HTML rendered on real devices and email clients (Gmail, Outlook, Apple Mail, mobile apps, and other supported platforms).\n\n**\ud83d\udcb3 Credit Cost:** Each preview request costs **2 credits**.", "operationId": "CreateEmailPreview", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "html", "devices" ], "properties": { "html": { "type": "string", "description": "Email HTML content to preview" }, "subject": { "type": "string", "default": "Email Preview", "description": "Email subject line (for display purposes)" }, "devices": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Specific devices to render on" }, "name": { "type": "string", "description": "Custom name for the preview" } } } } } }, "responses": { "200": { "description": "Preview creation started", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "previewId": { "type": "string" }, "status": { "type": "string", "enum": [ "processing", "completed", "partial", "failed" ] }, "name": { "type": "string" }, "subject": { "type": "string" }, "devices": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "properties": { "requestedDevices": { "type": "integer" }, "completedDevices": { "type": "integer" }, "failedDevices": { "type": "integer" }, "estimatedCompletionTime": { "type": "integer" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.previews.create({\n html: '...',\n subject: 'My Email Preview'\n});\n\n// Or wait for completion:\n// const result = await migma.previews.createAndWait({ ... });" } ] } }, "/v1/emails/previews/{previewId}": { "get": { "tags": [ "Email Previews" ], "summary": "Get Preview Status and Results", "description": "Retrieve the current status and complete results of an email preview, including all device screenshots. Note: This endpoint only retrieves results; credits (2 credits) are charged when creating the preview via POST /v1/emails/previews.", "operationId": "GetEmailPreview", "parameters": [ { "name": "previewId", "in": "path", "description": "Preview ID returned from create endpoint", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Preview retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "previewId": { "type": "string" }, "status": { "type": "string" }, "previewData": { "type": "object", "properties": { "previews": { "type": "array", "items": { "type": "object", "properties": { "deviceKey": { "type": "string" }, "deviceName": { "type": "string" }, "imageUrl": { "type": "string", "format": "uri" }, "thumbnailUrl": { "type": "string", "format": "uri" } } } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.previews.get('PREVIEW_ID');" } ] } }, "/v1/emails/previews/{previewId}/status": { "get": { "tags": [ "Email Previews" ], "summary": "Get Preview Status Only", "description": "Lightweight endpoint to check preview status without downloading full preview data. Optimized for polling.", "operationId": "GetEmailPreviewStatus", "parameters": [ { "name": "previewId", "in": "path", "description": "Preview ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Status retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "previewId": { "type": "string" }, "status": { "type": "string" }, "metadata": { "type": "object", "properties": { "requestedDevices": { "type": "integer" }, "completedDevices": { "type": "integer" }, "failedDevices": { "type": "integer" } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.previews.getStatus('PREVIEW_ID');" } ] } }, "/v1/emails/previews/{previewId}/devices/{deviceKey}": { "get": { "tags": [ "Email Previews" ], "summary": "Get Specific Device Preview", "description": "Get the preview screenshot for a single device.", "operationId": "GetEmailPreviewDevice", "parameters": [ { "name": "previewId", "in": "path", "description": "Preview ID", "required": true, "schema": { "type": "string" } }, { "name": "deviceKey", "in": "path", "description": "Device key (e.g., gmail_chrome, iphone13)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Device preview retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "device": { "type": "object", "properties": { "deviceKey": { "type": "string" }, "deviceName": { "type": "string" }, "status": { "type": "string" }, "imageUrl": { "type": "string", "format": "uri" }, "thumbnailUrl": { "type": "string", "format": "uri" } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.previews.getDevice(\n 'PREVIEW_ID',\n 'gmail-chrome'\n);" } ] } }, "/v1/emails/devices/supported": { "get": { "tags": [ "Email Previews" ], "summary": "Get Supported Devices", "description": "List device IDs available for email preview, grouped by platform (desktop, mobile, web).", "operationId": "GetSupportedDevices", "responses": { "200": { "description": "Supported devices list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "total": { "type": "integer" }, "categories": { "type": "object", "properties": { "desktop": { "type": "array", "items": { "type": "object" } }, "mobile": { "type": "array", "items": { "type": "object" } }, "web": { "type": "array", "items": { "type": "object" } } } }, "defaultDevices": { "type": "array", "items": { "type": "string" }, "description": "Default 10 devices used when none specified" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.previews.getSupportedDevices();" } ] } }, "/v1/shopify/connect": { "post": { "tags": [ "Integrations" ], "summary": "Connect Shopify Store", "description": "Connect a Shopify store to a project. Requires API key with email:read permission.", "operationId": "ConnectShopifyStore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectShopifyRequest" } } } }, "responses": { "200": { "description": "Shopify store connected successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseShopifyConnect" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/contacts": { "get": { "tags": [ "Contacts" ], "summary": "List Contacts", "description": "List contacts for a project. Requires API key with audience:read.", "operationId": "ListContacts", "parameters": [ { "name": "projectId", "in": "query", "description": "Project ID", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "Number of results per page (max 100)", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "tags", "in": "query", "description": "Comma-separated tag names", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by contact status", "required": false, "schema": { "type": "string", "enum": [ "subscribed", "unsubscribed", "bounced", "non-subscribed" ] } }, { "name": "search", "in": "query", "description": "Search query to filter contacts", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contacts list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseSubscribersList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.contacts.list({\n projectId: 'PROJECT_ID'\n});" } ] }, "post": { "tags": [ "Contacts" ], "summary": "Add Contact", "description": "Add a single contact. Requires API key with audience:write.", "operationId": "AddContact", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSubscriberRequest" } } } }, "responses": { "200": { "description": "Contact created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseSubscriber" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.contacts.create({\n email: 'john@example.com',\n firstName: 'John',\n lastName: 'Smith',\n status: 'subscribed',\n projectId: 'PROJECT_ID'\n});" } ] } }, "/v1/contacts/bulk": { "post": { "tags": [ "Contacts" ], "summary": "Bulk Import Contacts", "description": "Bulk import contacts. Requires API key with audience:write.", "operationId": "BulkImportContacts", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkImportSubscribersRequest" } } } }, "responses": { "200": { "description": "Bulk import result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseBulkImportResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.contacts.bulkImport({\n subscribers: [\n { email: 'john@example.com', firstName: 'John' },\n { email: 'jane@example.com', firstName: 'Jane' }\n ],\n projectId: 'PROJECT_ID'\n});" } ] } }, "/v1/contacts/bulk/{jobId}": { "get": { "tags": [ "Contacts" ], "summary": "Get Bulk Import Status", "description": "Poll an async JSON bulk import job. Requires API key with audience:read.", "operationId": "GetBulkImportStatus", "parameters": [ { "name": "jobId", "in": "path", "description": "Bulk import job ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "responses": { "200": { "description": "Bulk import job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseBulkImportJobStatus" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.contacts.getBulkImportStatus('JOB_ID');" } ] } }, "/v1/contacts/bulk-delete": { "post": { "tags": [ "Contacts" ], "summary": "Batch Delete Contacts", "description": "Delete up to 1000 contacts by email in a single request. Requires API key with audience:write. Partial-success-safe: emails with no matching contact are returned in `notFound`, never treated as errors.", "operationId": "BatchDeleteContacts", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteContactsRequest" } } } }, "responses": { "200": { "description": "Batch delete result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseBatchDeleteResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.migma.ai/v1/contacts/bulk-delete \\\n -H \"Authorization: Bearer $MIGMA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: contacts-delete-batch-1\" \\\n -d '{\n \"emails\": [\"john@example.com\", \"jane@example.com\"],\n \"projectId\": \"PROJECT_ID\"\n }'" } ] } }, "/v1/contacts/imports": { "post": { "tags": [ "Contacts" ], "summary": "Create Contact Import", "description": "Import contacts from an uploaded CSV file. The file is stored and processed in the background; poll `GET /v1/contacts/imports/{id}` for status and counts. Requires API key with audience:write.", "operationId": "CreateContactImport", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateContactImportRequest" } } } }, "responses": { "200": { "description": "Import accepted for background processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseContactImport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST https://api.migma.ai/v1/contacts/imports \\\n -H \"Authorization: Bearer $MIGMA_API_KEY\" \\\n -F \"file=@contacts.csv\" \\\n -F \"projectId=PROJECT_ID\" \\\n -F 'columnMap={\"email\":\"Email\",\"firstName\":\"First Name\"}' \\\n -F \"onConflict=upsert\" \\\n -F \"tags=newsletter,launch\"" } ] } }, "/v1/contacts/imports/{id}": { "get": { "tags": [ "Contacts" ], "summary": "Get Contact Import", "description": "Get a contact import's status and counts. Requires API key with audience:read.", "operationId": "GetContactImport", "parameters": [ { "name": "id", "in": "path", "description": "Import job ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "responses": { "200": { "description": "Import status and counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseContactImportStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl https://api.migma.ai/v1/contacts/imports/IMPORT_ID \\\n -H \"Authorization: Bearer $MIGMA_API_KEY\"" } ] } }, "/v1/contacts/status": { "post": { "tags": [ "Contacts" ], "summary": "Change Contact Status", "description": "Change a contact's subscription status by email. Requires API key with audience:write.", "operationId": "ChangeContactStatus", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeStatusRequest" } } } }, "responses": { "200": { "description": "Status updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.contacts.changeStatus({\n email: 'john@example.com',\n status: 'unsubscribed',\n projectId: 'PROJECT_ID'\n});" } ] } }, "/v1/contacts/{id}": { "get": { "tags": [ "Contacts" ], "summary": "Get Contact", "description": "Get a single contact by ID. Requires API key with audience:read.", "operationId": "GetContact", "parameters": [ { "name": "id", "in": "path", "description": "Contact ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } }, { "name": "projectId", "in": "query", "description": "Project ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contact details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseSubscriber" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.contacts.get(\n 'CONTACT_ID',\n 'PROJECT_ID'\n);" } ] }, "patch": { "tags": [ "Contacts" ], "summary": "Update Contact", "description": "Update a contact's details. Requires API key with audience:write.", "operationId": "UpdateContact", "parameters": [ { "name": "id", "in": "path", "description": "Contact ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactRequest" } } } }, "responses": { "200": { "description": "Contact updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseSubscriber" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.contacts.update('CONTACT_ID', {\n firstName: 'John',\n lastName: 'Smith',\n projectId: 'PROJECT_ID'\n});" } ] }, "delete": { "tags": [ "Contacts" ], "summary": "Delete Contact", "description": "Delete a contact. Requires API key with audience:write.", "operationId": "DeleteContact", "parameters": [ { "name": "id", "in": "path", "description": "Contact ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } }, { "name": "projectId", "in": "query", "description": "Project ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contact deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDeleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.contacts.remove(\n 'CONTACT_ID',\n 'PROJECT_ID'\n);" } ] } }, "/v1/tags": { "get": { "tags": [ "Tags" ], "summary": "List Tags", "description": "List tags for a project. Requires API key with audience:read.", "operationId": "ListTags", "parameters": [ { "name": "projectId", "in": "query", "description": "Project ID", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "Number of results per page (max 100)", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "search", "in": "query", "description": "Search query to filter tags by name", "required": false, "schema": { "type": "string" } }, { "name": "sortBy", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "enum": [ "createdAt", "name" ], "default": "createdAt" } }, { "name": "sortOrder", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "description": "Tags list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTagsList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.tags.list({\n projectId: 'PROJECT_ID'\n});" } ] }, "post": { "tags": [ "Tags" ], "summary": "Create Tag", "description": "Create a new tag. Requires API key with audience:write.", "operationId": "CreateTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTagRequest" } } } }, "responses": { "200": { "description": "Tag created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTag" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.tags.create({\n name: 'VIP Customers',\n color: '#6D28D9',\n projectId: 'PROJECT_ID'\n});" } ] } }, "/v1/tags/{id}": { "get": { "tags": [ "Tags" ], "summary": "Get Tag", "description": "Get a tag by ID. Requires API key with audience:read.", "operationId": "GetTag", "parameters": [ { "name": "id", "in": "path", "description": "Tag ID", "required": true, "schema": { "type": "string" } }, { "name": "projectId", "in": "query", "description": "Project ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tag details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTag" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.tags.get('TAG_ID', 'PROJECT_ID');" } ] }, "patch": { "tags": [ "Tags" ], "summary": "Update Tag", "description": "Update a tag. Requires API key with audience:write.", "operationId": "UpdateTag", "parameters": [ { "name": "id", "in": "path", "description": "Tag ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTagRequest" } } } }, "responses": { "200": { "description": "Tag updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTag" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.tags.update('TAG_ID', {\n name: 'Premium Customers',\n projectId: 'PROJECT_ID'\n});" } ] }, "delete": { "tags": [ "Tags" ], "summary": "Delete Tag", "description": "Delete a tag. Requires API key with audience:write.", "operationId": "DeleteTag", "parameters": [ { "name": "id", "in": "path", "description": "Tag ID", "required": true, "schema": { "type": "string" } }, { "name": "projectId", "in": "query", "description": "Project ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tag deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDeleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.tags.remove('TAG_ID', 'PROJECT_ID');" } ] } }, "/v1/topics": { "get": { "tags": [ "Topics" ], "summary": "List Topics", "description": "List topics for a project. Requires API key with audience:read.", "operationId": "ListTopics", "parameters": [ { "name": "projectId", "in": "query", "description": "Project ID", "required": true, "schema": { "type": "string" } }, { "name": "includeInactive", "in": "query", "description": "Include inactive topics", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Topics list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTopicsList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.topics.list({\n projectId: 'PROJECT_ID'\n});" } ] }, "post": { "tags": [ "Topics" ], "summary": "Create Topic", "description": "Create a new topic. Requires API key with audience:write.", "operationId": "CreateTopic", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTopicRequest" } } } }, "responses": { "200": { "description": "Topic created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTopic" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.topics.create({\n name: 'Weekly Newsletter',\n description: 'Our weekly product updates',\n defaultSubscription: 'opt_in',\n projectId: 'PROJECT_ID'\n});" } ] } }, "/v1/topics/{id}": { "get": { "tags": [ "Topics" ], "summary": "Get Topic", "description": "Get a topic by ID. Requires API key with audience:read.", "operationId": "GetTopic", "parameters": [ { "name": "id", "in": "path", "description": "Topic ID", "required": true, "schema": { "type": "string" } }, { "name": "projectId", "in": "query", "description": "Project ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Topic details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTopic" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.topics.get('TOPIC_ID', 'PROJECT_ID');" } ] }, "patch": { "tags": [ "Topics" ], "summary": "Update Topic", "description": "Update a topic. Note: defaultSubscription cannot be changed after creation. Requires API key with audience:write.", "operationId": "UpdateTopic", "parameters": [ { "name": "id", "in": "path", "description": "Topic ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTopicRequest" } } } }, "responses": { "200": { "description": "Topic updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTopic" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.topics.update('TOPIC_ID', {\n name: 'Monthly Digest',\n projectId: 'PROJECT_ID'\n});" } ] }, "delete": { "tags": [ "Topics" ], "summary": "Delete Topic", "description": "Delete a topic. Requires API key with audience:write.", "operationId": "DeleteTopic", "parameters": [ { "name": "id", "in": "path", "description": "Topic ID", "required": true, "schema": { "type": "string" } }, { "name": "projectId", "in": "query", "description": "Project ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Topic deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDeleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.topics.remove('TOPIC_ID', 'PROJECT_ID');" } ] } }, "/v1/topics/{id}/subscribe": { "post": { "tags": [ "Topics" ], "summary": "Subscribe Contact to Topic", "description": "Subscribe a contact to a topic. Requires API key with audience:write.", "operationId": "SubscribeToTopic", "parameters": [ { "name": "id", "in": "path", "description": "Topic ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicSubscriptionRequest" } } } }, "responses": { "200": { "description": "Subscription updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTopicSubscription" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.topics.subscribe('TOPIC_ID', {\n subscriberId: 'CONTACT_ID',\n projectId: 'PROJECT_ID'\n});" } ] } }, "/v1/topics/{id}/unsubscribe": { "post": { "tags": [ "Topics" ], "summary": "Unsubscribe Contact from Topic", "description": "Unsubscribe a contact from a topic. Requires API key with audience:write.", "operationId": "UnsubscribeFromTopic", "parameters": [ { "name": "id", "in": "path", "description": "Topic ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicSubscriptionRequest" } } } }, "responses": { "200": { "description": "Subscription updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTopicSubscription" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.topics.unsubscribe('TOPIC_ID', {\n subscriberId: 'CONTACT_ID',\n projectId: 'PROJECT_ID'\n});" } ] } }, "/v1/segments": { "get": { "tags": [ "Segments" ], "summary": "List Segments", "description": "List segments for a project. Requires API key with audience:read.", "operationId": "ListSegments", "parameters": [ { "name": "projectId", "in": "query", "description": "Project ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Segments list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseAudiencesList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.segments.list('PROJECT_ID');" } ] }, "post": { "tags": [ "Segments" ], "summary": "Create Segment", "description": "Create a new segment with optional filters. Requires API key with audience:write.", "operationId": "CreateSegment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAudienceRequest" } } } }, "responses": { "200": { "description": "Segment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseAudience" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.segments.create({\n name: 'Campaign openers',\n description: 'Users who opened a specific campaign in the last 14 days',\n filters: {\n activity: [{\n action: 'opened',\n channel: 'email',\n mode: 'within',\n unit: 'days',\n amount: 14,\n campaignId: 'CAMPAIGN_ID'\n }]\n },\n projectId: 'PROJECT_ID'\n});" } ] } }, "/v1/segments/{id}": { "get": { "tags": [ "Segments" ], "summary": "Get Segment", "description": "Get a segment by ID with contact count. Requires API key with audience:read.", "operationId": "GetSegment", "parameters": [ { "name": "id", "in": "path", "description": "Segment ID", "required": true, "schema": { "type": "string" } }, { "name": "projectId", "in": "query", "description": "Project ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Segment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseAudience" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.segments.get(\n 'SEGMENT_ID',\n 'PROJECT_ID'\n);" } ] }, "patch": { "tags": [ "Segments" ], "summary": "Update Segment", "description": "Update a segment. Requires API key with audience:write.", "operationId": "UpdateSegment", "parameters": [ { "name": "id", "in": "path", "description": "Segment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAudienceRequest" } } } }, "responses": { "200": { "description": "Segment updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseAudience" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.segments.update('SEGMENT_ID', {\n name: 'Power Users',\n projectId: 'PROJECT_ID'\n});" } ] }, "delete": { "tags": [ "Segments" ], "summary": "Delete Segment", "description": "Delete a segment. Requires API key with audience:write.", "operationId": "DeleteSegment", "parameters": [ { "name": "id", "in": "path", "description": "Segment ID", "required": true, "schema": { "type": "string" } }, { "name": "projectId", "in": "query", "description": "Project ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Segment deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDeleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.segments.remove(\n 'SEGMENT_ID',\n 'PROJECT_ID'\n);" } ] } }, "/v1/domains": { "get": { "tags": [ "Domains" ], "summary": "List Domains", "description": "List all sending domains for the authenticated user. Requires API key with domain:read.", "operationId": "ListDomains", "responses": { "200": { "description": "Domains list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDomainsList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.domains.list();" } ] }, "post": { "tags": [ "Domains" ], "summary": "Add Domain", "description": "Add a new sending domain. Returns DNS records that must be configured for verification. Requires API key with domain:write.", "operationId": "AddDomain", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddDomainRequest" } } } }, "responses": { "200": { "description": "Domain added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDomain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.domains.create({\n domain: 'mail.yourbrand.com'\n});" } ] } }, "/v1/domains/{domain}": { "get": { "tags": [ "Domains" ], "summary": "Get Domain", "description": "Get domain details by domain name. Requires API key with domain:read.", "operationId": "GetDomain", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name (e.g., mail.example.com)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Domain details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDomain" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.domains.get('mail.yourbrand.com');" } ] }, "patch": { "tags": [ "Domains" ], "summary": "Update Domain Settings", "description": "Update domain tracking settings. Requires API key with domain:write.", "operationId": "UpdateDomainSettings", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDomainSettingsRequest" } } } }, "responses": { "200": { "description": "Domain settings updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDomain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.domains.update(\n 'mail.yourbrand.com',\n { openTracking: true, clickTracking: true }\n);" } ] }, "delete": { "tags": [ "Domains" ], "summary": "Delete Domain", "description": "Delete a sending domain. Requires API key with domain:write.", "operationId": "DeleteDomain", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Domain deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDeleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.domains.remove('mail.yourbrand.com');" } ] } }, "/v1/domains/{domain}/verify": { "post": { "tags": [ "Domains" ], "summary": "Verify Domain", "description": "Trigger DNS verification for a domain. Returns current verification status. Requires API key with domain:write.", "operationId": "VerifyDomain", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDomainVerification" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.domains.verify('mail.yourbrand.com');" } ] } }, "/v1/domains/managed/check/{prefix}": { "get": { "tags": [ "Domains" ], "summary": "Check Subdomain Availability", "description": "Check if a managed subdomain prefix is available on migma.email. Requires API key with domain:read.", "operationId": "CheckSubdomainAvailability", "parameters": [ { "name": "prefix", "in": "path", "description": "Subdomain prefix to check (e.g., 'acme' for acme.migma.email)", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 63 } } ], "responses": { "200": { "description": "Availability result", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SubdomainAvailability" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.domains.checkAvailability(\n 'yourcompany'\n);" } ] } }, "/v1/domains/streams": { "post": { "tags": [ "Domains" ], "summary": "Provision Stream Identity", "description": "Provision a transactional or marketing sending identity on a domain you own. Creates notify. (transactional) or send. (marketing) to isolate transactional reputation from marketing. Returns DNS records to publish, then verify. Requires API key with domain:write.", "operationId": "ProvisionStreamIdentity", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionStreamRequest" } } } }, "responses": { "201": { "description": "Stream identity provisioned. Publish the returned DNS records, then verify.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDomain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.domains.provisionStream({\n rootDomain: 'acme.com',\n stream: 'transactional'\n});" } ] } }, "/v1/domains/managed": { "get": { "tags": [ "Domains" ], "summary": "List Managed Domains", "description": "List all managed subdomains (migma.email) for the authenticated user. Requires API key with domain:read.", "operationId": "ListManagedDomains", "responses": { "200": { "description": "Managed domains list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDomainsList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.domains.listManaged();" } ] }, "post": { "tags": [ "Domains" ], "summary": "Create Managed Domain", "description": "Create a managed subdomain on migma.email. The domain is instantly verified with no DNS setup required. Requires API key with domain:write.", "operationId": "CreateManagedDomain", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManagedDomainRequest" } } } }, "responses": { "200": { "description": "Managed domain created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDomain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.domains.createManaged({\n prefix: 'yourcompany'\n});" } ] } }, "/v1/domains/managed/{domain}": { "delete": { "tags": [ "Domains" ], "summary": "Delete Managed Domain", "description": "Delete a managed subdomain. Requires API key with domain:write.", "operationId": "DeleteManagedDomain", "parameters": [ { "name": "domain", "in": "path", "description": "Full managed domain name (e.g., acme.migma.email)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Managed domain deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseSuccess" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.domains.removeManaged(\n 'yourcompany.migma.email'\n);" } ] } }, "/v1/domains/setup": { "post": { "tags": [ "Domains" ], "summary": "Set Up Domain", "description": "Provision the main sending identity (bare root domain) and notify. (transactional) on a domain you own in one call. The main identity is used for campaigns and hand sends; notify. is for receipts and password resets. If a legacy send. marketing identity already exists, it is included in the response; new setups do not create marketing. Idempotent. Safe to call again if DNS records already exist. Returns DNS records for each provisioned identity. Requires API key with domains:write.", "operationId": "SetupDomain", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rootDomain" ], "properties": { "rootDomain": { "type": "string", "description": "The apex domain you own, e.g. 'acme.com'" }, "fromName": { "type": "string", "description": "Default From display name for provisioned identities." }, "vanityRootFrom": { "type": "boolean", "description": "Show the apex domain in the From header when DMARC passes. Defaults to true." } } } } } }, "responses": { "200": { "description": "Domain setup complete", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/SetupDomainResult" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.domains.setup({\n rootDomain: 'acme.com'\n});" } ] } }, "/v1/domains/purchase/search": { "get": { "tags": [ "Domains" ], "summary": "Search Buyable Domains", "description": "Check availability and yearly price for domains matching a query. Requires API key with domain:read permission.", "operationId": "SearchBuyableDomains", "parameters": [ { "name": "q", "in": "query", "description": "Domain or keyword to search, e.g. 'acme' or 'acme.com'", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120 } }, { "name": "limit", "in": "query", "description": "Maximum number of quotes to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 8 } } ], "responses": { "200": { "description": "Domain availability and pricing quotes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDomainPurchaseSearch" }, "example": { "success": true, "data": { "quotes": [ { "rootDomain": "acme.com", "tld": "com", "available": false, "supported": true }, { "rootDomain": "acme.io", "tld": "io", "available": true, "supported": true, "premium": false, "sellPrice": 48.0, "currency": "USD" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/domains/purchase": { "post": { "tags": [ "Domains" ], "summary": "Purchase Domain", "description": "Start a domain purchase. Returns a Stripe checkout URL the account owner opens and pays in a browser. Domains are billed yearly and renew automatically. The domain registers only after payment clears, and failed registrations are refunded automatically. Requires an active paid Migma subscription (returns 409 otherwise) and an API key with domain:write permission.", "operationId": "PurchaseDomain", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseDomainRequest" } } } }, "responses": { "200": { "description": "Domain purchase started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDomainPurchaseStarted" }, "example": { "success": true, "data": { "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_live_...", "checkoutSessionId": "cs_live_...", "billingMode": "annual_subscription" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/domains/purchase/registrations": { "get": { "tags": [ "Domains" ], "summary": "List Domain Purchases", "description": "List domain purchases and their registration status. Status moves from payment_pending to registering to active, or to failed or refunded. Requires API key with domain:read permission.", "operationId": "ListDomainPurchases", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of registrations to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Domain purchase registrations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDomainPurchaseRegistrations" }, "example": { "success": true, "data": { "registrations": [ { "id": "reg_abc123", "rootDomain": "acme.io", "status": "active", "sellPrice": 48.0, "currency": "USD" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/domains/{domain}/dns-records": { "get": { "tags": [ "Domains" ], "summary": "List DNS Records", "description": "List DNS records on a domain whose DNS zone is hosted by Migma. Only domains bought in Migma have Migma-hosted zones; for other domains managed is false and records is empty. Requires API key with domain:read permission.", "operationId": "ListDnsRecords", "parameters": [ { "name": "domain", "in": "path", "description": "The domain, e.g. 'acme.io'", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "DNS records for the domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDnsRecords" }, "example": { "success": true, "data": { "managed": true, "records": [ { "id": "rec_abc123", "type": "TXT", "name": "@", "content": "google-site-verification=abc123", "createdAt": "2026-08-20T12:00:00.000Z" }, { "id": "rec_def456", "type": "MX", "name": "@", "content": "smtp.google.com", "priority": 1, "createdAt": "2026-08-20T12:00:00.000Z" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Domains" ], "summary": "Add DNS Record", "description": "Add a DNS record to a domain bought in Migma, for example Google Workspace MX records, a site-verification TXT, or an A record pointing a subdomain at a server. Migma's email sending records are protected and managed automatically, duplicate SPF or DMARC records are refused, the root and www names are reserved for domain forwarding, and each domain is capped at 50 records. Returns 404 if the domain's DNS zone is not hosted by Migma. Requires API key with domain:write permission.", "operationId": "AddDnsRecord", "parameters": [ { "name": "domain", "in": "path", "description": "The domain, e.g. 'acme.io'", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddDnsRecordRequest" } } } }, "responses": { "201": { "description": "DNS record created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDnsRecordCreated" }, "example": { "success": true, "data": { "record": { "id": "rec_abc123", "type": "TXT", "name": "@", "content": "google-site-verification=abc123", "createdAt": "2026-08-20T12:00:00.000Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/domains/{domain}/dns-records/{recordId}": { "delete": { "tags": [ "Domains" ], "summary": "Remove DNS Record", "description": "Remove a DNS record that was added to a domain bought in Migma. Only removes records the user added, never Migma's own sending records. Requires API key with domain:write permission.", "operationId": "RemoveDnsRecord", "parameters": [ { "name": "domain", "in": "path", "description": "The domain, e.g. 'acme.io'", "required": true, "schema": { "type": "string" } }, { "name": "recordId", "in": "path", "description": "Id of the DNS record to remove", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "DNS record removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDnsRecordRemoved" }, "example": { "success": true, "data": { "ok": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/sending": { "post": { "tags": [ "Emails" ], "summary": "Send Email", "description": "Send one generated email to a single recipient, audience, segment, or tag. Provide emailId to send a specific email from a conversation or series. conversationId remains supported for single-email conversations. All sends are queued for background delivery and return immediately with status queued. Single-recipient sends are transactional by default; batch sends default to marketing. Requires API key with email:send.", "operationId": "SendEmail", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailRequest" } } } }, "responses": { "200": { "description": "Email sent or batch queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseSendEmail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.sending.send({\n recipientType: 'email',\n recipientEmail: 'recipient@example.com',\n from: 'hello@yourbrand.migma.email',\n fromName: 'Your Brand',\n subject: 'Hello!',\n emailId: 'EMAIL_ID'\n});" }, { "lang": "javascript", "label": "Batch Transactional", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.sending.send({\n recipientType: 'tag',\n recipientId: 'TAG_ID',\n from: 'noreply@yourbrand.migma.email',\n fromName: 'Your Brand',\n subject: 'Your subscription renews tomorrow',\n emailId: 'EMAIL_ID',\n transactional: true\n});" } ] } }, "/v1/sending/batches/{batchId}": { "get": { "tags": [ "Emails" ], "summary": "Get Batch Status", "description": "Get the status of a batch email send. Requires API key with email:read.", "operationId": "GetBatchStatus", "parameters": [ { "name": "batchId", "in": "path", "description": "Batch ID returned from send email", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Batch status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseBatchStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.sending.getBatchStatus('BATCH_ID');" } ] } }, "/v1/metrics/sending": { "get": { "tags": [ "Emails" ], "summary": "Get Sending Metrics", "description": "Get account-level sending totals, quota usage, and optional monthly history. Requires API key with email:read permission.", "operationId": "GetSendingMetrics", "parameters": [ { "name": "months", "in": "query", "description": "Number of previous monthly periods to include in history. Omit to exclude history.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 12 } } ], "responses": { "200": { "description": "Account sending metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseSendingMetrics" }, "example": { "success": true, "data": { "period": "2026-07", "monthly": { "sent": 0, "delivered": 0, "bounced": 0, "complained": 0 }, "today": { "sent": 0, "reserved": 0, "dailyLimit": 0, "remainingToday": 0 }, "monthlyLimit": 0, "remainingMonth": 0, "history": [ { "period": "2026-06", "sent": 0, "delivered": 0, "bounced": 0, "complained": 0 } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/campaigns": { "get": { "tags": [ "Campaigns" ], "summary": "List Campaigns", "description": "List campaigns for a project. Requires API key with campaign:read.", "operationId": "ListCampaigns", "parameters": [ { "name": "projectId", "in": "query", "description": "Project ID", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by campaign status", "required": false, "schema": { "type": "string", "enum": [ "draft", "pending_review", "scheduled", "sending", "throttled", "sent", "failed", "cancelled" ] } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "Number of results per page", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "List of campaigns", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseListCampaigns" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.campaigns.list({ projectId: 'PROJECT_ID' });" } ] }, "post": { "tags": [ "Campaigns" ], "summary": "Create Campaign", "description": "Create a new email campaign from a generated email. Use emailId for the exact generated email, especially series slots. Requires API key with campaign:write.", "operationId": "CreateCampaign", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCampaignRequest" } } } }, "responses": { "200": { "description": "Campaign created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseCampaign" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.campaigns.create({\n projectId: 'PROJECT_ID',\n name: 'Investor Update',\n conversationId: 'CONVERSATION_ID',\n emailId: 'EMAIL_ID',\n from: 'hello@yourbrand.migma.email',\n fromName: 'Your Brand',\n recipientType: 'tag',\n recipientId: 'TAG_ID'\n});" } ] } }, "/v1/campaigns/{id}": { "get": { "tags": [ "Campaigns" ], "summary": "Get Campaign", "description": "Get a single campaign by ID. Requires API key with campaign:read.", "operationId": "GetCampaign", "parameters": [ { "name": "id", "in": "path", "description": "Campaign ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Campaign details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseCampaign" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.campaigns.get('CAMPAIGN_ID');" } ] } }, "/v1/campaigns/{id}/send": { "post": { "tags": [ "Campaigns" ], "summary": "Send Campaign", "description": "Send a draft or scheduled campaign immediately. Re-extracts the latest template at send time. Requires API key with campaign:write.", "operationId": "SendCampaign", "parameters": [ { "name": "id", "in": "path", "description": "Campaign ID", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Campaign sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseCampaign" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.campaigns.send('CAMPAIGN_ID');" } ] } }, "/v1/campaigns/{id}/schedule": { "post": { "tags": [ "Campaigns" ], "summary": "Schedule Campaign", "description": "Schedule a campaign for future delivery. scheduledAt must be in the future. Requires API key with campaign:write.", "operationId": "ScheduleCampaign", "parameters": [ { "name": "id", "in": "path", "description": "Campaign ID", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleCampaignRequest" } } } }, "responses": { "200": { "description": "Campaign scheduled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseCampaign" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.campaigns.schedule('CAMPAIGN_ID', {\n scheduledAt: '2026-03-15T14:00:00Z',\n scheduledTimezone: 'America/New_York'\n});" } ] } }, "/v1/campaigns/{id}/cancel": { "post": { "tags": [ "Campaigns" ], "summary": "Cancel Campaign", "description": "Cancel an eligible campaign. The returned campaign has status cancelled. Requires API key with campaign:write.", "operationId": "CancelCampaign", "parameters": [ { "name": "id", "in": "path", "description": "Campaign ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Campaign cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseCampaign" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.campaigns.cancel('CAMPAIGN_ID');" } ] } }, "/v1/campaigns/{id}/archive": { "post": { "tags": [ "Campaigns" ], "summary": "Archive Campaign", "description": "Archive a campaign to hide it from the default campaign list. Works for any status. Archived campaigns are excluded from list results unless the archived filter is set. Requires API key with campaign:write.", "operationId": "ArchiveCampaign", "parameters": [ { "name": "id", "in": "path", "description": "Campaign ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Campaign archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseCampaign" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.campaigns.archive('CAMPAIGN_ID');" } ] } }, "/v1/campaigns/{id}/unarchive": { "post": { "tags": [ "Campaigns" ], "summary": "Unarchive Campaign", "description": "Restore a previously archived campaign, making it visible in the default list again. Requires API key with campaign:write.", "operationId": "UnarchiveCampaign", "parameters": [ { "name": "id", "in": "path", "description": "Campaign ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Campaign unarchived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseCampaign" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.campaigns.unarchive('CAMPAIGN_ID');" } ] } }, "/v1/campaigns/{id}/stats": { "get": { "tags": [ "Campaigns" ], "summary": "Get Campaign Stats", "description": "Get aggregate engagement stats for a sent campaign (sends, deliveries, opens, clicks, unsubscribes, bounces, and rates). Stats are sourced from the tracking worker and may be cached and slightly stale. botOpens, botClicks, and mppOpens reflect Apple Mail Privacy Protection and bot detection when available. Requires API key with campaign:read.", "operationId": "GetCampaignStats", "parameters": [ { "name": "id", "in": "path", "description": "Campaign ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Campaign stats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseCampaignStats" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.campaigns.stats('CAMPAIGN_ID');" } ] } }, "/v1/campaigns/{id}/logs": { "get": { "tags": [ "Campaigns" ], "summary": "Get Campaign Logs", "description": "List per-recipient delivery and engagement logs for a campaign, newest first. Cursor-paginated. Rows come from the tracking worker (D1) and use snake_case field names. Requires API key with campaign:read.", "operationId": "GetCampaignLogs", "parameters": [ { "name": "id", "in": "path", "description": "Campaign ID", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of rows to return (max 100).", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's nextCursor. Omit for the first page.", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by delivery or engagement status.", "required": false, "schema": { "type": "string", "enum": [ "delivered", "opened", "clicked", "bounced", "spam_report" ] } } ], "responses": { "200": { "description": "Campaign logs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseCampaignLogs" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.campaigns.logs('CAMPAIGN_ID', {\n limit: 50,\n status: 'opened'\n});" } ] } }, "/v1/export/html/{conversationId}": { "get": { "tags": [ "Emails" ], "summary": "Export HTML", "description": "Export conversation as standard HTML.", "operationId": "ExportHTML", "parameters": [ { "name": "conversationId", "in": "path", "description": "The conversation ID to export", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTML export successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseExport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.export.html('CONVERSATION_ID');" } ] } }, "/v1/export/klaviyo/{conversationId}": { "get": { "tags": [ "Emails" ], "summary": "Export Klaviyo", "description": "Export conversation as Klaviyo-compatible HTML with editable regions.", "operationId": "ExportKlaviyo", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "The conversation ID to export", "schema": { "type": "string" } }, { "name": "klaviyoType", "in": "query", "description": "Type of Klaviyo export: 'html' for static HTML or 'hybrid' for dynamic hybrid with editable regions", "required": false, "schema": { "type": "string", "enum": [ "html", "hybrid" ], "default": "hybrid" } } ], "responses": { "200": { "description": "Klaviyo export successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseExport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.export.klaviyo('CONVERSATION_ID');" } ] } }, "/v1/export/mailchimp/{conversationId}": { "get": { "tags": [ "Emails" ], "summary": "Export Mailchimp", "description": "Export conversation as Mailchimp-compatible HTML. Returns URLs for file downloads.", "operationId": "ExportMailchimp", "parameters": [ { "name": "conversationId", "in": "path", "description": "The conversation ID to export", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Mailchimp export successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseExport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.export.mailchimp('CONVERSATION_ID');" } ] } }, "/v1/export/hubspot": { "post": { "tags": [ "Emails" ], "summary": "Export HubSpot", "description": "Export conversation as HubSpot-compatible HTML and HubL files.", "operationId": "ExportHubSpot", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "description": "The conversation ID to export" }, "customOptions": { "type": "object", "description": "Custom options for HubSpot export", "properties": { "customInstructions": { "type": "string", "description": "Custom instructions for the export" } } } }, "required": [ "conversationId" ] } } } }, "responses": { "200": { "description": "HubSpot export successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseExport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.export.hubspot({\n conversationId: 'CONVERSATION_ID'\n});" } ] } }, "/v1/export/status/{conversationId}": { "get": { "tags": [ "Emails" ], "summary": "Get Export Status", "description": "Check export availability for a conversation", "operationId": "GetExportStatus", "parameters": [ { "name": "conversationId", "in": "path", "description": "The conversation ID to check", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Export status retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseExportStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.export.getStatus('CONVERSATION_ID');" } ] } }, "/v1/export/formats": { "get": { "tags": [ "Emails" ], "summary": "List Export Formats", "description": "Get available export formats", "operationId": "ListExportFormats", "responses": { "200": { "description": "Available export formats retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseExportFormats" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.export.getFormats();" } ] } }, "/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List Webhooks", "description": "List all webhooks for the authenticated user. Requires API key with webhook:read.", "operationId": "ListWebhooks", "responses": { "200": { "description": "Webhooks list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseWebhooksList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.webhooks.list();" } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Create Webhook", "description": "Create a new webhook endpoint. Returns the webhook configuration including a secret for signature verification. The secret is only shown once. Requires API key with webhook:write.", "operationId": "CreateWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "201": { "description": "Webhook created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseWebhookCreated" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.webhooks.create({\n url: 'https://yourapp.com/webhooks/migma',\n events: ['email.generation.completed', 'subscriber.unsubscribed']\n});" } ] } }, "/v1/webhooks/stats": { "get": { "tags": [ "Webhooks" ], "summary": "Get Webhook Stats", "description": "Get aggregate webhook statistics including total counts and delivery metrics. Requires API key with webhook:read.", "operationId": "GetWebhookStats", "responses": { "200": { "description": "Webhook statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseWebhookStats" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.webhooks.getStats();" } ] } }, "/v1/webhooks/events": { "get": { "tags": [ "Webhooks" ], "summary": "List Event Types", "description": "List all available webhook event types with descriptions. Requires API key with webhook:read.", "operationId": "ListWebhookEventTypes", "responses": { "200": { "description": "Event types list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseWebhookEvents" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.webhooks.getEvents();" } ] } }, "/v1/webhooks/{webhookId}": { "get": { "tags": [ "Webhooks" ], "summary": "Get Webhook", "description": "Get webhook details by ID. Requires API key with webhook:read.", "operationId": "GetWebhook", "parameters": [ { "name": "webhookId", "in": "path", "description": "Webhook ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "responses": { "200": { "description": "Webhook details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseWebhookDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.webhooks.get('WEBHOOK_ID');" } ] }, "patch": { "tags": [ "Webhooks" ], "summary": "Update Webhook", "description": "Update a webhook configuration. Requires API key with webhook:write.", "operationId": "UpdateWebhook", "parameters": [ { "name": "webhookId", "in": "path", "description": "Webhook ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } } }, "responses": { "200": { "description": "Webhook updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.webhooks.update('WEBHOOK_ID', {\n active: false\n});" } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete Webhook", "description": "Delete a webhook configuration. Requires API key with webhook:write.", "operationId": "DeleteWebhook", "parameters": [ { "name": "webhookId", "in": "path", "description": "Webhook ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "responses": { "200": { "description": "Webhook deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDeleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.webhooks.remove('WEBHOOK_ID');" } ] } }, "/v1/webhooks/{webhookId}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Test Webhook", "description": "Send a test event to a webhook endpoint to verify it is configured correctly. Returns the HTTP status code and response time. Requires API key with webhook:write.", "operationId": "TestWebhook", "parameters": [ { "name": "webhookId", "in": "path", "description": "Webhook ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "responses": { "200": { "description": "Test result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseWebhookTest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.webhooks.test('WEBHOOK_ID');" } ] } }, "/v1/webhooks/{webhookId}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "Get Webhook Deliveries", "description": "Get recent delivery attempts for a specific webhook. Requires API key with webhook:read.", "operationId": "GetWebhookDeliveries", "parameters": [ { "name": "webhookId", "in": "path", "description": "Webhook ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } }, { "name": "limit", "in": "query", "description": "Maximum number of deliveries to return (max 100)", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100 } } ], "responses": { "200": { "description": "Webhook deliveries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseWebhookDeliveries" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.webhooks.getDeliveries('WEBHOOK_ID');" } ] } }, "/v1/projects/{projectId}/images": { "post": { "tags": [ "Project Editing" ], "summary": "Add Image", "description": "Add an image to a project by URL. Requires project:write permission.", "operationId": "AddImage", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddImageRequest" } } } }, "responses": { "200": { "description": "Image added", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectImage" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Project Editing" ], "summary": "Update Image Metadata", "description": "Update image description and tags. Requires project:write permission.", "operationId": "UpdateImageMetadata", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateImageRequest" } } } }, "responses": { "200": { "description": "Image metadata updated", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectImage" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Project Editing" ], "summary": "Remove Image", "description": "Remove an image from a project. Requires project:write permission.", "operationId": "RemoveImage", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } }, { "name": "imageUrl", "in": "query", "description": "URL of the image to remove (URL-encoded)", "required": true, "schema": { "type": "string", "format": "uri" } } ], "responses": { "200": { "description": "Image removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseSuccess" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{projectId}/knowledge-base": { "get": { "tags": [ "Project Editing" ], "summary": "List Knowledge Base Entries", "description": "Get all knowledge base entries for a project. Requires email:read permission.", "operationId": "ListKnowledgeBase", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "responses": { "200": { "description": "Knowledge base entries retrieved", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeBaseEntry" } }, "total": { "type": "integer" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Project Editing" ], "summary": "Add Knowledge Base Entry", "description": "Add a new knowledge base entry to a project. Requires project:write permission.", "operationId": "AddKnowledgeBaseEntry", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddKnowledgeBaseRequest" } } } }, "responses": { "200": { "description": "Knowledge base entry added", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KnowledgeBaseEntry" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{projectId}/knowledge-base/{entryId}": { "put": { "tags": [ "Project Editing" ], "summary": "Update Knowledge Base Entry", "description": "Update an existing knowledge base entry. Requires project:write permission.", "operationId": "UpdateKnowledgeBaseEntry", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } }, { "name": "entryId", "in": "path", "description": "Knowledge base entry ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKnowledgeBaseRequest" } } } }, "responses": { "200": { "description": "Knowledge base entry updated", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KnowledgeBaseEntry" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Project Editing" ], "summary": "Remove Knowledge Base Entry", "description": "Remove a knowledge base entry from a project. Requires project:write permission.", "operationId": "RemoveKnowledgeBaseEntry", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } }, { "name": "entryId", "in": "path", "description": "Knowledge base entry ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Knowledge base entry removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseSuccess" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{projectId}/logos": { "put": { "tags": [ "Project Editing" ], "summary": "Update Logos", "description": "Update project logos (primary, secondary, favicon). Requires project:write permission.", "operationId": "UpdateLogos", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID (MongoDB ObjectId)", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLogosRequest" } } } }, "responses": { "200": { "description": "Logos updated", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "logoUrls": { "$ref": "#/components/schemas/LogoUrls" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/emails/{emailId}": { "get": { "tags": [ "Emails" ], "summary": "Get Email", "description": "Fetch one generated email by emailId. Returns production-ready HTML, subject, preheader, and screenshot URLs.", "operationId": "GetEmail", "parameters": [ { "name": "emailId", "in": "path", "description": "Email ID returned in generation status result.emails[].emailId.", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "responses": { "200": { "description": "Email retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseEmail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data } = await migma.emails.get('EMAIL_ID');\nconsole.log(data.html);\nconsole.log(data.screenshotUrl);" } ] } }, "/v1/emails/{emailId}/metrics": { "get": { "tags": [ "Emails" ], "summary": "Get Email Metrics", "description": "Aggregate performance for one generated email across every API send of it: delivery, opens, clicks, bounces, complaints, unsubscribes, plus a daily time series and country breakdown. Numbers arrive asynchronously and cover roughly the last 30 days of raw history (aggregates persist longer). Opens are directional \u2014 Apple Mail Privacy Protection and bots inflate them; clicks and delivery events are stronger signals. Requires the email:read scope.", "operationId": "GetEmailMetrics", "parameters": [ { "name": "emailId", "in": "path", "description": "Email ID returned in generation status result.emails[].emailId.", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "responses": { "200": { "description": "Email metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseEmailMetrics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data } = await migma.emails.metrics('EMAIL_ID');\nconsole.log(data.summary);" } ] } }, "/v1/emails/{emailId}/logs": { "get": { "tags": [ "Emails" ], "summary": "Get Email Logs", "description": "Per-recipient send log for one generated email, cursor-paginated. Filter by status. Returns { emails, nextCursor, hasMore }. Individual rows are retained roughly 30 days. Requires the email:read scope.", "operationId": "GetEmailLogs", "parameters": [ { "name": "emailId", "in": "path", "description": "Email ID returned in generation status result.emails[].emailId.", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } }, { "name": "limit", "in": "query", "required": false, "description": "Max rows per page (capped at 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous response's nextCursor.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter rows by delivery/engagement status.", "schema": { "type": "string", "enum": [ "delivered", "opened", "clicked", "bounced", "complained", "suppressed", "sent" ] } } ], "responses": { "200": { "description": "Email send log", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseEmailLogs" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data } = await migma.emails.logs('EMAIL_ID', { limit: 50 });\nconsole.log(data.emails);" } ] } }, "/v1/emails/{emailId}/edit": { "post": { "tags": [ "Emails" ], "summary": "Edit Email With Prompt", "description": "Prompt Migma to edit one generated email as a canvas follow-up turn (same orchestrator path as design chat). The same emailId remains valid; the response returns updated HTML and screenshot URLs. Requires API key with email:write permission.", "operationId": "EditEmailWithPrompt", "parameters": [ { "name": "emailId", "in": "path", "required": true, "description": "Email ID returned in generation status result.emails[].emailId.", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditEmailRequest" } } } }, "responses": { "200": { "description": "Email edited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseEmail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data } = await migma.emails.edit('EMAIL_ID', {\n prompt: 'Make this welcome email shorter and more transactional'\n});\n\nconsole.log(data.html);" } ] } }, "/v1/events": { "post": { "tags": [ "Events" ], "summary": "Track Event", "description": "Record a customer event for a project. Requires the audience:write permission. Contact resolution is consent safe: profile fields may update, subscription status never changes. Send an Idempotency-Key header (or a body dedupeKey) for replay safety; without either, every call stores a distinct event. Events carrying identifiers.externalOrderId and a numeric properties.value are recorded as conversions attributed to the last email the contact clicked within five days.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Replay-safe key. Takes precedence over the body dedupeKey." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestEventRequest" }, "example": { "projectId": "PROJECT_ID", "name": "purchase.completed", "identifiers": { "email": "ada@example.com", "externalOrderId": "order_8891" }, "properties": { "value": 49.99, "currency": "USD" } } } } }, "responses": { "201": { "description": "Event stored (or replayed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTrackEventResult" } } } }, "400": { "description": "Validation failed or no contact identifier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "403": { "description": "Missing audience:write permission or no access to the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "404": { "description": "Subscriber not found in this project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } } } }, "/v1/events/batch": { "post": { "tags": [ "Events" ], "summary": "Track Events (Batch)", "description": "Record up to 500 events in one request with row-level partial success: one malformed row never fails the batch. Idempotency is per row via dedupeKey; a request-level Idempotency-Key header is rejected. Aggregate properties payloads are limited to 1MB.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "projectId", "events" ], "properties": { "projectId": { "type": "string" }, "events": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/IngestEventRow" } } } } } } }, "responses": { "201": { "description": "Batch processed with per-row results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTrackEventBatchResult" } } } }, "400": { "description": "Envelope invalid, aggregate payload too large, or request-level Idempotency-Key supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "403": { "description": "Missing audience:write permission or no access to the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } } } }, "/v1/export/pdf/{conversationId}": { "get": { "tags": [ "Emails" ], "summary": "Export PDF", "description": "Export conversation as a PDF document. Returns a download URL.", "operationId": "ExportPDF", "parameters": [ { "name": "conversationId", "in": "path", "description": "The conversation ID to export", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "PDF export successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseExport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.export.pdf('CONVERSATION_ID');" } ] } }, "/v1/export/png/{conversationId}": { "get": { "tags": [ "Emails" ], "summary": "Export PNG", "description": "Export conversation as a PNG image of the email. Returns a download URL.", "operationId": "ExportPNG", "parameters": [ { "name": "conversationId", "in": "path", "description": "The conversation ID to export", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "PNG export successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseExport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js SDK", "source": "import Migma from 'migma';\n\nconst migma = new Migma('YOUR_API_KEY');\n\nconst { data, error } = await migma.export.png('CONVERSATION_ID');" } ] } }, "/v1/billing/credits": { "get": { "tags": [ "Billing" ], "summary": "Get Credits", "description": "Get the current plan and remaining email, image, and monthly credits for the API key owner. Requires API key with billing:read permission.", "operationId": "GetCredits", "responses": { "200": { "description": "Plan and remaining credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseBillingCredits" }, "example": { "success": true, "data": { "currentPlan": "premium", "isExpired": false, "planExpiry": "2026-09-14T00:00:00.000Z", "hasCredits": true, "emailCreditsRemainingToday": 40, "imageCreditsRemainingToday": 25, "monthlyCreditsRemaining": 310 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/billing/upgrade-link": { "post": { "tags": [ "Billing" ], "summary": "Create Upgrade Link", "description": "Create a Stripe link the account owner opens in a browser to upgrade or manage their subscription. Nothing is charged by this call. Pass a plan to get a checkout link for that plan; existing subscribers may get an in-place plan change or a billing portal link instead. Omit plan to get a billing portal link for existing Stripe customers (returns 400 otherwise). Requires API key with billing:write permission.", "operationId": "CreateUpgradeLink", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUpgradeLinkRequest" } } } }, "responses": { "200": { "description": "Billing link created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseUpgradeLink" }, "example": { "success": true, "data": { "url": "https://checkout.stripe.com/c/pay/cs_live_...", "kind": "checkout", "sessionId": "cs_live_..." } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } } }, "components": { "responses": { "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "BadRequest": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "Forbidden": { "description": "Forbidden - Missing required permissions or access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "Conflict": { "description": "Conflict - the Idempotency-Key was reused with a different request body (code: IDEMPOTENCY_CONFLICT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional key (max 100 chars) for safe retries. Same key + same body within 24h replays the original response (same status and body); same key + a different body returns 409 IDEMPOTENCY_CONFLICT. Scoped per API key.", "schema": { "type": "string", "maxLength": 100 } } }, "schemas": { "ApiResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "nullable": true }, "error": { "type": "string", "nullable": true } }, "required": [ "success" ] }, "ApiError": { "type": "object", "properties": { "success": { "type": "boolean", "default": false }, "error": { "type": "string" }, "code": { "type": "string", "description": "Machine-readable error code (e.g., IDEMPOTENCY_CONFLICT, DOMAIN_CLAIMABLE)." }, "data": { "type": "object", "description": "Additional structured context for the error, such as the affected domain.", "additionalProperties": true } }, "required": [ "success", "error" ] }, "LogoUrls": { "type": "object", "properties": { "primary": { "type": "string", "format": "uri" }, "secondary": { "type": "string", "format": "uri" }, "favicon": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "ImportProjectRequest": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 10 }, "logoUrls": { "$ref": "#/components/schemas/LogoUrls" } }, "required": [ "urls" ] }, "ImportStartedData": { "type": "object", "properties": { "projectId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "status": { "type": "string", "enum": [ "pending" ] }, "domain": { "type": "string" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "message": { "type": "string" } }, "required": [ "projectId", "status", "domain", "urls" ] }, "ImportStatusProgress": { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "initializing", "analyzing", "completed", "failed", "pending", "processing", "unknown" ] }, "percentage": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 100 } }, "required": [ "stage", "percentage" ] }, "ImportStatusData": { "type": "object", "properties": { "projectId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "status": { "type": "string", "enum": [ "pending", "processing", "active", "error" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "domain": { "type": "string" }, "error": { "type": "string", "nullable": true }, "progress": { "$ref": "#/components/schemas/ImportStatusProgress" } }, "required": [ "status", "name", "description", "progress" ] }, "ImportRetryData": { "type": "object", "properties": { "projectId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "status": { "type": "string", "enum": [ "pending" ] }, "message": { "type": "string" } }, "required": [ "status" ] }, "EmailImageSource": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ], "default": "url" }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, "EmailImage": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/EmailImageSource" } }, "required": [ "source" ] }, "GenerateEmailRequest": { "type": "object", "properties": { "projectId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "prompt": { "type": "string" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/EmailImage" }, "maxItems": 5 }, "model": { "type": "string", "default": "migmaAI-model-v0.1" }, "webMode": { "type": "boolean", "default": true, "description": "Allow MigmaAI to do research, use connectors, mcp and more. It may take longer to generate the email. Use only if the prompt is unclear or requires additional information." }, "languages": { "type": "array", "items": { "type": "string" }, "maxItems": 5, "description": "The languages to generate the email in. If not provided, the email will be generated as instructed by the prompt." }, "visibility": { "type": "string", "enum": [ "private", "unlisted", "public" ], "default": "private", "description": "Set the visibility of the generated conversation. Private conversations are only visible to the user, unlisted conversations are accessible via direct link but not listed publicly, and public conversations are visible in the public gallery." }, "referenceId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "Optional conversation ID to remix so you can create personalized variants from an existing conversation." }, "count": { "type": "integer", "minimum": 1, "maximum": 12, "description": "Optional target number of emails to generate for a series. Omit to let Migma infer single email vs series from the prompt." } }, "required": [ "projectId", "prompt" ] }, "ImportHtmlEmailFile": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200, "description": "Filename, e.g. welcome.html or message.eml" }, "source": { "type": "string", "description": "HTML document or raw .eml source. Max 250KB per file." } }, "required": [ "name", "source" ] }, "ImportHtmlEmailRequest": { "type": "object", "properties": { "projectId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "html": { "type": "string", "description": "Single HTML or .eml source. Provide html or htmls, not both." }, "name": { "type": "string", "maxLength": 200, "description": "Filename for a single html paste." }, "htmls": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "$ref": "#/components/schemas/ImportHtmlEmailFile" }, "description": "Multiple HTML or .eml files. One file becomes one canvas slot." }, "instruction": { "type": "string", "maxLength": 20000, "description": "Natural-language conversion instruction (keep as-is vs apply brand)." }, "languages": { "type": "array", "items": { "type": "string" }, "maxItems": 5 }, "visibility": { "type": "string", "enum": [ "private", "unlisted", "public" ], "default": "unlisted" }, "generateMedia": { "type": "boolean", "description": "Generate AI media for missing images. Defaults to the project setting, then true." } }, "required": [ "projectId" ] }, "ListEmailsEmail": { "type": "object", "properties": { "conversationId": { "type": "string", "description": "The conversation ID" }, "title": { "type": "string", "description": "Conversation title (truncated prompt)" }, "subject": { "type": "string", "nullable": true, "description": "Email subject line" }, "previewText": { "type": "string", "nullable": true, "description": "Email preview text" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "description": "Generation status" }, "screenshotUrl": { "type": "string", "nullable": true, "description": "Email screenshot URL" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ListEmailsData": { "type": "object", "properties": { "emails": { "type": "array", "items": { "$ref": "#/components/schemas/ListEmailsEmail" } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of emails" }, "page": { "type": "integer", "description": "Current page number" }, "limit": { "type": "integer", "description": "Results per page" }, "hasMore": { "type": "boolean", "description": "Whether more results exist" } } } } }, "GenerateEmailData": { "type": "object", "properties": { "conversationId": { "type": "string", "description": "The conversation ID to check status and retrieve results" }, "status": { "type": "string", "enum": [ "pending" ], "description": "Initial status is always pending" }, "message": { "type": "string", "description": "Information message about the generation process" }, "link": { "type": "string", "format": "uri", "description": "Direct link to view the generated email. Unlisted and public generations return https://migma.ai/share/{conversationId}; private generations return https://migma.ai/chat?c={conversationId}." }, "count": { "type": "integer", "description": "Requested email count, when provided." }, "referenceId": { "type": "string", "description": "Reference conversation used for remixing, when provided." } }, "required": [ "conversationId", "status", "message", "link" ] }, "EmailStatusData": { "type": "object", "properties": { "conversationId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "error": { "type": "string", "description": "Error message if status is failed" }, "result": { "type": "object", "description": "Full email content and metadata, present when status is completed. result.html/result.subject identify the primary email; use result.emails[] for per-email IDs, HTML, screenshots, and series order.", "properties": { "subject": { "type": "string", "description": "Email subject line" }, "previewText": { "type": "string", "description": "Email preview text shown in inbox" }, "html": { "type": "string", "description": "Production-ready HTML for the primary email." }, "screenshotUrl": { "type": "string", "format": "uri", "description": "URL to email screenshot preview" }, "screenshotFullUrl": { "type": "string", "format": "uri", "description": "URL to full-length email screenshot" }, "stats": { "type": "object", "description": "Email statistics and metadata", "properties": { "imageCount": { "type": "integer", "description": "Number of images in the email" }, "buttonCount": { "type": "integer", "description": "Number of buttons/CTAs in the email" }, "estimatedLength": { "type": "string", "description": "Estimated email length (short, medium, long)" }, "colors": { "type": "array", "items": { "type": "string" }, "description": "Colors used in the email" } } }, "languages": { "type": "array", "items": { "type": "string" }, "description": "Languages the email was generated in" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/GeneratedEmail" }, "description": "All active generated emails. Use emailId from this array to fetch, edit, test-send, or send one email from a series." }, "seriesPlan": { "type": "object", "additionalProperties": true, "description": "Series planning metadata when the generation produced multiple emails." } } } }, "required": [ "conversationId", "status", "createdAt", "updatedAt" ] }, "Project": { "type": "object", "properties": { "_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "active", "error" ] }, "companyDetails": { "type": "object", "additionalProperties": true }, "logoUrls": { "$ref": "#/components/schemas/LogoUrls" }, "imageUrls": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "typography": { "type": "object", "additionalProperties": true }, "colors": { "type": "object", "additionalProperties": true }, "screenshotUrl": { "type": "string", "format": "uri" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "ProjectBasic": { "type": "object", "properties": { "_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "active", "error" ] }, "domain": { "type": "string" }, "logoUrls": { "$ref": "#/components/schemas/LogoUrls" }, "screenshotUrl": { "type": "string", "format": "uri" }, "email_create_suggestions": { "type": "array", "items": { "type": "string" }, "description": "AI-generated suggestions for email content creation based on the project context" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "_id", "name", "description", "status", "createdAt", "updatedAt" ] }, "Pagination": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "offset": { "type": "integer", "format": "int32" }, "hasMore": { "type": "boolean" } }, "required": [ "total", "limit", "offset", "hasMore" ] }, "ProjectsListData": { "type": "object", "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectBasic" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "projects", "pagination" ] }, "ApiResponseImportStarted": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ImportStartedData" } } } ] }, "ApiResponseImportStatus": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ImportStatusData" } } } ] }, "ApiResponseImportRetry": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ImportRetryData" } } } ] }, "ApiResponseGenerateEmail": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GenerateEmailData" } } } ] }, "ApiResponseEmailStatus": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EmailStatusData" } } } ] }, "SendTestEmailRequest": { "type": "object", "properties": { "emailId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "Email ID to test-send. Recommended for generated emails and required for series slots." }, "conversationId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "Single-email conversation ID. For series, use emailId." }, "to": { "type": "string", "format": "email", "description": "Recipient email address" } }, "required": [ "to" ], "anyOf": [ { "required": [ "emailId" ] }, { "required": [ "conversationId" ] } ] }, "TestEmailSentData": { "type": "object", "properties": { "messageId": { "type": "string", "description": "Message ID from the email service" }, "conversationId": { "type": "string", "description": "The conversation ID that was used" }, "sentTo": { "type": "string", "format": "email", "description": "Recipient email address" }, "sentAt": { "type": "string", "format": "date-time", "description": "Timestamp when the email was sent" }, "subject": { "type": "string", "description": "The subject line that was sent" } }, "required": [ "messageId", "conversationId", "sentTo", "sentAt", "subject" ] }, "ApiResponseTestEmailSent": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TestEmailSentData" } } } ] }, "ConnectShopifyRequest": { "type": "object", "properties": { "projectId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The project ID to connect the Shopify store to" }, "shopifyStoreUrl": { "type": "string", "format": "uri", "description": "The Shopify store URL (e.g., https://example.com or https://store.myshopify.com)" } }, "required": [ "projectId", "shopifyStoreUrl" ] }, "ShopifyConnectData": { "type": "object", "properties": { "serverId": { "type": "string", "description": "The MCP server ID created for this Shopify connection" }, "projectId": { "type": "string", "description": "The project ID" }, "status": { "type": "string", "enum": [ "connected" ], "description": "Connection status: 'connected' (successful)" }, "message": { "type": "string", "description": "Status message" }, "store": { "type": "string", "description": "The Shopify store name extracted from the URL" }, "toolsEnabled": { "type": "array", "items": { "type": "string" }, "description": "List of enabled Shopify tool names" } }, "required": [ "serverId", "projectId", "status", "message", "store", "toolsEnabled" ] }, "ApiResponseShopifyConnect": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ShopifyConnectData" } } } ] }, "ApiResponseProject": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Project" } } } ] }, "ApiResponseProjectsList": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectsListData" } } } ] }, "FieldCatalogEntry": { "type": "object", "description": "A single subscriber field discovered in the project, with its fill rate and example values.", "properties": { "key": { "type": "string", "description": "Stable slug used in templates (e.g. firstName, company)." }, "label": { "type": "string", "description": "Human-readable label for UI." }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "date", "url", "unknown" ], "description": "Inferred value type. V1 returns 'string' for everything; future passes will infer richer types." }, "fillRate": { "type": "number", "minimum": 0, "maximum": 1, "description": "Share of subscribers in the scope with a non-empty value (0\u20131)." }, "sample": { "type": "array", "items": { "type": "string" }, "description": "Up to 3 example values, each truncated to 50 characters. Empty for auto fields." }, "auto": { "type": "boolean", "description": "True for native fields auto-filled at send time (email, firstName, etc.)." } }, "required": [ "key", "label", "type", "fillRate", "sample", "auto" ] }, "FieldCatalogResponse": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/FieldCatalogEntry" } }, "totalSubscribers": { "type": "integer", "description": "Total subscribers in the scoped set the catalog was computed over." }, "computedAt": { "type": "string", "format": "date-time", "description": "When the catalog was computed. Catalogs are cached for up to 1 hour." } }, "required": [ "entries", "totalSubscribers", "computedAt" ] }, "ApiResponseFieldCatalog": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FieldCatalogResponse" } } } ] }, "Subscriber": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phone": { "type": "string", "maxLength": 30, "description": "Phone number" }, "country": { "type": "string" }, "language": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "customFields": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "subscribed", "unsubscribed", "bounced", "non-subscribed" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AddSubscriberRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phone": { "type": "string", "maxLength": 30, "description": "Phone number (free-form, max 30 chars)" }, "country": { "type": "string" }, "language": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "customFields": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "description": "Contact subscription status. Defaults to subscribed.", "enum": [ "subscribed", "unsubscribed", "bounced", "non-subscribed" ] }, "projectId": { "type": "string" } }, "required": [ "email", "projectId" ] }, "BulkImportSubscribersRequest": { "type": "object", "properties": { "subscribers": { "type": "array", "items": { "$ref": "#/components/schemas/AddSubscriberRequest" }, "minItems": 1 }, "projectId": { "type": "string" } }, "required": [ "subscribers", "projectId" ] }, "ChangeStatusRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email address of the contact" }, "status": { "type": "string", "enum": [ "subscribed", "unsubscribed", "bounced", "non-subscribed" ], "description": "New status for the contact" }, "allLists": { "type": "boolean", "default": true, "description": "Apply to all lists" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Specific tag IDs to scope the status change" }, "projectId": { "type": "string", "description": "Project ID" } }, "required": [ "email", "status", "projectId" ] }, "ApiResponseSubscriber": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Subscriber" } } } ] }, "ApiResponseSubscribersList": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Subscriber" } }, "count": { "type": "integer" } } } ] }, "ApiResponseBulkImportResult": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "integer" }, "failed": { "type": "integer" }, "updated": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "string" } } } } } } ] }, "ApiResponseBulkImportJobStatus": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "totalContacts": { "type": "integer" }, "processed": { "type": "integer" }, "result": { "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } } } } } ] }, "CreateContactImportRequest": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "CSV file to import" }, "projectId": { "type": "string", "description": "Project ID" }, "columnMap": { "type": "string", "description": "JSON string mapping subscriber fields to CSV header names. Only `email` is required. Supported keys: `email`, `firstName`, `lastName`, `name`, `phone`, `country`, `language`, and `customFields` (an object mapping each custom field key to its CSV header). Example: `{\"email\":\"Email\",\"firstName\":\"First Name\",\"customFields\":{\"plan\":\"Plan\"}}`." }, "onConflict": { "type": "string", "enum": [ "skip", "upsert" ], "default": "upsert", "description": "How to handle rows whose email already exists." }, "delimiter": { "type": "string", "default": ",", "description": "CSV field delimiter." }, "tags": { "type": "string", "description": "Tag names to apply to every imported contact, as a JSON array (e.g. `[\"newsletter\"]`) or a comma-separated string. Tags are created if they do not exist." } }, "required": [ "file", "projectId", "columnMap" ] }, "ApiResponseContactImport": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "contact_import" }, "id": { "type": "string", "description": "Import job ID. Poll GET /v1/contacts/imports/{id} for status." }, "status": { "type": "string", "example": "processing" } } } } } ] }, "ApiResponseContactImportStatus": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "object": { "type": "string", "example": "contact_import" }, "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "counts": { "type": "object", "properties": { "total": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" } } }, "error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } } } } ] }, "ApiResponseSuccess": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } ] }, "ExportFile": { "type": "object", "properties": { "filename": { "type": "string", "description": "Name of the exported file" }, "url": { "type": "string", "format": "uri", "description": "Download URL for the exported file" }, "content": { "type": "string", "description": "File content" }, "format": { "type": "string", "enum": [ "html", "hubl", "json", "text", "png" ], "description": "Format of the exported file" }, "description": { "type": "string", "description": "Description of the exported file" }, "fileSize": { "type": "number", "description": "File size in bytes" } }, "required": [ "filename", "content", "format", "description" ], "additionalProperties": false }, "V1ExportFile": { "type": "object", "properties": { "filename": { "type": "string", "description": "Name of the exported file" }, "url": { "type": "string", "format": "uri", "description": "Download URL for the exported file" }, "content": { "type": "string", "description": "File content" }, "format": { "type": "string", "enum": [ "html", "hubl", "json", "text", "png" ], "description": "Format of the exported file" }, "description": { "type": "string", "description": "Description of the exported file" }, "fileSize": { "type": "number", "description": "File size in bytes" } }, "required": [ "filename", "url", "content", "format", "description", "fileSize" ], "additionalProperties": false }, "StandardExportFile": { "type": "object", "properties": { "filename": { "type": "string", "description": "Name of the exported file" }, "content": { "type": "string", "description": "File content" }, "format": { "type": "string", "enum": [ "html", "hubl", "json", "text", "png" ], "description": "Format of the exported file" }, "description": { "type": "string", "description": "Description of the exported file" } }, "required": [ "filename", "content", "format", "description" ], "additionalProperties": false }, "ExportData": { "type": "object", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/V1ExportFile" }, "description": "Array of exported files with download URLs and content" }, "executionTime": { "type": "number", "description": "Export execution time in milliseconds" }, "exportType": { "type": "string", "enum": [ "html", "klaviyo", "mailchimp", "png", "hubspot" ], "description": "Type of export performed" } }, "required": [ "files", "executionTime", "exportType" ] }, "StandardExportData": { "type": "object", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/StandardExportFile" }, "description": "Array of exported files with content" }, "executionTime": { "type": "number", "description": "Export execution time in milliseconds" }, "exportType": { "type": "string", "enum": [ "html", "klaviyo", "mailchimp", "png", "hubspot" ], "description": "Type of export performed" } }, "required": [ "files", "executionTime", "exportType" ] }, "ApiResponseExport": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExportData" } } } ] }, "ExportStatusData": { "type": "object", "properties": { "conversationId": { "type": "string", "description": "The conversation ID" }, "canExport": { "type": "boolean", "description": "Whether the conversation can be exported" }, "availableFormats": { "type": "array", "items": { "type": "string" }, "description": "Available export formats for this conversation" }, "reason": { "type": "string", "description": "Reason if export is not available" } }, "required": [ "conversationId", "canExport", "availableFormats" ] }, "ApiResponseExportStatus": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExportStatusData" } } } ] }, "ExportFormat": { "type": "object", "properties": { "name": { "type": "string", "description": "Format name" }, "description": { "type": "string", "description": "Format description" }, "supportedFormats": { "type": "array", "items": { "type": "string" }, "description": "Supported file formats" }, "type": { "type": "string", "enum": [ "simple", "complex" ], "description": "Export complexity type" } }, "required": [ "name", "description", "supportedFormats", "type" ] }, "ExportFormatsData": { "type": "object", "properties": { "formats": { "type": "array", "items": { "$ref": "#/components/schemas/ExportFormat" }, "description": "Available export formats" }, "total": { "type": "integer", "description": "Total number of available formats" } }, "required": [ "formats", "total" ] }, "ApiResponseExportFormats": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExportFormatsData" } } } ] }, "CreateWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The webhook endpoint URL (must be HTTPS)" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Array of event types to subscribe to (e.g., email.generation.completed)" }, "description": { "type": "string", "description": "Optional description for the webhook" }, "customHeaders": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional custom headers to include in webhook requests" } }, "required": [ "url", "events" ] }, "UpdateWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The webhook endpoint URL (must be HTTPS)" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Array of event types to subscribe to" }, "active": { "type": "boolean", "description": "Whether the webhook is active" }, "description": { "type": "string", "description": "Optional description for the webhook" }, "customHeaders": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional custom headers to include in webhook requests" } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook ID" }, "url": { "type": "string", "format": "uri", "description": "The webhook endpoint URL" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed event types" }, "active": { "type": "boolean", "description": "Whether the webhook is active" }, "secretConfigured": { "type": "boolean", "description": "Whether a signing secret is configured. The secret value itself is returned only once, in the create response." }, "description": { "type": "string", "description": "Optional description" }, "successCount": { "type": "integer", "description": "Number of successful deliveries" }, "failureCount": { "type": "integer", "description": "Number of failed deliveries" }, "lastTriggeredAt": { "type": "string", "format": "date-time", "description": "Last trigger timestamp" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } }, "WebhookWithSecret": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Webhook secret for signature verification (only shown once upon creation)" } } } ] }, "WebhookEvent": { "type": "object", "properties": { "type": { "type": "string", "description": "Event type identifier" }, "description": { "type": "string", "description": "Event description" } } }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "description": "Delivery ID" }, "eventId": { "type": "string", "description": "Event ID (for idempotency)" }, "eventType": { "type": "string", "description": "Event type" }, "status": { "type": "string", "enum": [ "pending", "sending", "success", "failed", "retry" ], "description": "Delivery status" }, "attempts": { "type": "integer", "description": "Number of delivery attempts" }, "lastAttemptAt": { "type": "string", "format": "date-time", "description": "Last attempt timestamp" }, "response": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "HTTP status code" }, "error": { "type": "string", "description": "Error message if failed" } } }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } } }, "WebhookStats": { "type": "object", "properties": { "totalWebhooks": { "type": "integer", "description": "Total number of webhooks" }, "activeWebhooks": { "type": "integer", "description": "Number of active webhooks" }, "deliveries": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total deliveries" }, "success": { "type": "integer", "description": "Successful deliveries" }, "failed": { "type": "integer", "description": "Failed deliveries" }, "pending": { "type": "integer", "description": "Pending deliveries" } } } } }, "ApiResponseWebhooksList": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "total": { "type": "integer" } } } } } ] }, "ApiResponseWebhookCreated": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookWithSecret" } } } ] }, "ApiResponseWebhookDetail": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } ] }, "ApiResponseWebhookEvents": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "total": { "type": "integer" } } } } } ] }, "ApiResponseWebhookStats": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookStats" } } } ] }, "ApiResponseWebhookTest": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "statusCode": { "type": "integer" }, "responseTime": { "type": "integer", "description": "Response time in milliseconds" } } } } } ] }, "ApiResponseWebhookDeliveries": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "total": { "type": "integer" } } } } } ] }, "ApiResponseDeleted": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } ] }, "BatchDeleteContactsRequest": { "type": "object", "required": [ "emails", "projectId" ], "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "maxItems": 1000, "description": "Email addresses to delete (1-1000 per request)." }, "projectId": { "type": "string" } } }, "ApiResponseBatchDeleteResult": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "integer", "description": "Number of contacts actually deleted." }, "notFound": { "type": "array", "items": { "type": "string" }, "description": "Submitted emails with no matching contact (not an error)." } } } } } ] }, "UpdateContactRequest": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phone": { "type": "string", "maxLength": 30, "description": "Phone number (free-form, max 30 chars). Null clears the field.", "nullable": true }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "nullable": true }, "language": { "type": "string", "description": "Language code (ISO 639-1 or BCP 47)", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tag names (tags will be auto-created if they don't exist)" }, "customFields": { "type": "object", "additionalProperties": true, "description": "Merged into the contact's existing custom fields \u2014 fields you don't include are left untouched. Pass an empty object to clear all custom fields." }, "status": { "type": "string", "enum": [ "subscribed", "unsubscribed", "bounced", "non-subscribed" ] }, "projectId": { "type": "string" } }, "required": [ "projectId" ] }, "Tag": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "description": "Hex color code" }, "description": { "type": "string" }, "subscriberCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreateTagRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "color": { "type": "string", "description": "Hex color code (e.g., #FF5733). Auto-generated if omitted.", "pattern": "^#[0-9a-fA-F]{6}$" }, "description": { "type": "string", "maxLength": 500 }, "projectId": { "type": "string" } }, "required": [ "name", "projectId" ] }, "UpdateTagRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "description": { "type": "string", "maxLength": 500 }, "projectId": { "type": "string" } }, "required": [ "projectId" ] }, "ApiResponseTag": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tag" } } } ] }, "ApiResponseTagsList": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "count": { "type": "integer" } } } ] }, "Topic": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "defaultSubscription": { "type": "string", "enum": [ "opt_in", "opt_out" ] }, "visibility": { "type": "string", "enum": [ "public", "private" ] }, "displayOrder": { "type": "integer" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreateTopicRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "defaultSubscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "default": "opt_out", "description": "Cannot be changed after creation. opt_out means all contacts are subscribed by default." }, "visibility": { "type": "string", "enum": [ "public", "private" ], "default": "public" }, "displayOrder": { "type": "integer", "minimum": 0 }, "projectId": { "type": "string" } }, "required": [ "name", "projectId" ] }, "UpdateTopicRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "visibility": { "type": "string", "enum": [ "public", "private" ] }, "displayOrder": { "type": "integer", "minimum": 0 }, "isActive": { "type": "boolean" }, "projectId": { "type": "string" } }, "required": [ "projectId" ] }, "TopicSubscriptionRequest": { "type": "object", "properties": { "subscriberId": { "type": "string", "description": "Contact ID to subscribe/unsubscribe" }, "projectId": { "type": "string" } }, "required": [ "subscriberId", "projectId" ] }, "ApiResponseTopic": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Topic" } } } ] }, "ApiResponseTopicsList": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Topic" } }, "count": { "type": "integer" } } } ] }, "ApiResponseTopicSubscription": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "topicId": { "type": "string" }, "subscriberId": { "type": "string" }, "subscribed": { "type": "boolean" } } } } } ] }, "AudienceFilters": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } }, "excludeTags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "subscribed", "unsubscribed", "non-subscribed", "bounced" ] }, "validationStatus": { "type": "string", "enum": [ "valid", "invalid", "risky", "unknown" ] }, "customFields": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "fields": { "type": "array", "maxItems": 10, "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 100 }, "mode": { "type": "string", "enum": [ "is", "is_not", "starts_with", "ends_with", "contains", "not_contains", "date_after", "date_before", "date_on", "date_between", "number_gt", "number_gte", "number_lt", "number_lte", "number_between" ], "default": "is" }, "values": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "key", "values" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "sent", "opened", "clicked" ] }, "channel": { "type": "string", "enum": [ "email" ], "description": "Email is the only supported activity channel today." }, "mode": { "type": "string", "enum": [ "within", "before", "never", "between" ], "description": "between is reserved and currently rejected." }, "unit": { "type": "string", "enum": [ "hours", "days" ] }, "amount": { "type": "integer", "minimum": 1, "maximum": 8760, "description": "Required for within/before. days: 1-365, hours: 1-8760." }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "campaignId": { "type": "string" } }, "required": [ "action", "mode" ] } } } }, "Audience": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "filters": { "$ref": "#/components/schemas/AudienceFilters" }, "count": { "type": "integer", "description": "Number of contacts matching the segment filters" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreateAudienceRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 500 }, "filters": { "$ref": "#/components/schemas/AudienceFilters" }, "projectId": { "type": "string" } }, "required": [ "name", "projectId" ] }, "UpdateAudienceRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 500 }, "filters": { "$ref": "#/components/schemas/AudienceFilters" }, "projectId": { "type": "string" } }, "required": [ "projectId" ] }, "ApiResponseAudience": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Audience" } } } ] }, "ApiResponseAudiencesList": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Audience" } }, "count": { "type": "integer" } } } ] }, "DnsRecord": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CNAME", "TXT", "MX" ] }, "name": { "type": "string" }, "value": { "type": "string" }, "priority": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "verified", "failed" ] } } }, "SendingDomain": { "type": "object", "properties": { "_id": { "type": "string" }, "domain": { "type": "string" }, "region": { "type": "string", "enum": [ "us-east-1", "eu-west-1", "us-east-2" ], "description": "AWS region the domain sends from. Automatically assigned at creation.", "readOnly": true }, "regionName": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "verifying", "verified", "degraded", "failed", "suspended" ] }, "dkimStatus": { "type": "string", "enum": [ "SUCCESS", "PENDING", "FAILED", "NOT_STARTED" ] }, "mailFromDomain": { "type": "string" }, "mailFromStatus": { "type": "string", "enum": [ "SUCCESS", "PENDING", "FAILED" ] }, "dnsRecords": { "type": "array", "items": { "$ref": "#/components/schemas/DnsRecord" } }, "ownershipVerified": { "type": "boolean" }, "openTracking": { "type": "boolean" }, "clickTracking": { "type": "boolean" }, "brandedTracking": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "verifiedAt": { "type": "string", "format": "date-time", "nullable": true }, "isManagedDomain": { "type": "boolean" } } }, "CreateManagedDomainRequest": { "type": "object", "properties": { "prefix": { "type": "string", "minLength": 3, "maxLength": 63, "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$", "description": "Subdomain prefix (e.g., 'acme' creates acme.migma.email). Lowercase letters, numbers, and hyphens only." } }, "required": [ "prefix" ] }, "ProvisionStreamRequest": { "type": "object", "properties": { "rootDomain": { "type": "string", "description": "Apex domain you own (e.g., 'acme.com'). The stream subdomain is derived from it." }, "stream": { "type": "string", "enum": [ "transactional", "marketing" ], "description": "'transactional' provisions notify.; 'marketing' provisions send.." }, "vanityRootFrom": { "type": "boolean", "default": false, "description": "Show the apex domain in the From header when its DMARC passes." } }, "required": [ "rootDomain", "stream" ] }, "SubdomainAvailability": { "type": "object", "properties": { "available": { "type": "boolean", "description": "Whether the subdomain is available" }, "prefix": { "type": "string", "description": "The prefix that was checked" }, "fullDomain": { "type": "string", "description": "The full domain name (e.g., acme.migma.email)" }, "reason": { "type": "string", "description": "Reason if not available" } } }, "AddDomainRequest": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain name (e.g., mail.example.com)" } }, "required": [ "domain" ] }, "UpdateDomainSettingsRequest": { "type": "object", "properties": { "openTracking": { "type": "boolean", "description": "Enable/disable open tracking" }, "clickTracking": { "type": "boolean", "description": "Enable/disable click tracking" }, "brandedTracking": { "type": "boolean", "description": "Enable/disable branded tracking links" } } }, "DomainVerificationResult": { "type": "object", "properties": { "domain": { "type": "string" }, "status": { "type": "string", "enum": [ "verified", "degraded", "verifying", "failed", "pending" ] }, "dkimStatus": { "type": "string" }, "mailFromStatus": { "type": "string" }, "dnsRecords": { "type": "array", "items": { "$ref": "#/components/schemas/DnsRecord" } }, "allVerified": { "type": "boolean" }, "dnsIssues": { "type": "array", "items": { "type": "string" } } } }, "ApiResponseDomain": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SendingDomain" } } } ] }, "ApiResponseDomainsList": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SendingDomain" } }, "count": { "type": "integer" } } } ] }, "ApiResponseDomainVerification": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DomainVerificationResult" } } } ] }, "SetupDomainResult": { "type": "object", "required": [ "main", "transactional" ], "properties": { "main": { "$ref": "#/components/schemas/SendingDomain", "description": "Bare root domain for campaigns and hand sends." }, "transactional": { "$ref": "#/components/schemas/SendingDomain", "description": "notify. identity for receipts and password resets." }, "marketing": { "$ref": "#/components/schemas/SendingDomain", "description": "Legacy send. identity, included only when it already existed." } } }, "SendEmailRequest": { "type": "object", "properties": { "recipientType": { "type": "string", "enum": [ "email", "audience", "segment", "tag" ], "description": "Type of recipient. 'email' for single send, 'audience' or 'segment' for segment-based batch sends, 'tag' for tag-based batch sends." }, "recipientId": { "type": "string", "description": "Required for audience/segment/tag sends. The segment or tag ID." }, "recipientEmail": { "type": "string", "format": "email", "description": "Required for single email sends." }, "from": { "type": "string", "format": "email", "description": "Sender email address (must be from a verified domain)" }, "fromName": { "type": "string", "description": "Sender display name" }, "replyTo": { "type": "string", "format": "email" }, "subject": { "type": "string" }, "variables": { "type": "object", "additionalProperties": true, "description": "Template variables for personalization" }, "providerType": { "type": "string", "description": "Email service provider to send through. Defaults to Migma's built-in sending. To use an external provider, connect it first in Settings \u2192 Integrations \u2192 Email Providers.", "enum": [ "ses", "resend", "sendgrid", "mailgun", "migma" ], "default": "migma" }, "projectId": { "type": "string", "description": "Project ID. Optional when emailId or conversationId resolves the project automatically." }, "conversationId": { "type": "string", "description": "Conversation ID from a generated email. Works for single-email conversations. For series, use emailId." }, "transactional": { "type": "boolean", "description": "Controls whether the email is treated as transactional (order confirmations, password resets) or marketing. Defaults to true for single sends (recipientType 'email') and false for batch sends (recipientType 'audience', 'segment', 'tag'). Transactional emails bypass subscription status and topic preference filters, and omit List-Unsubscribe headers. Bounced and invalid addresses are always excluded. Set explicitly to override the default." }, "emailId": { "type": "string", "description": "Generated email ID from result.emails[].emailId. Recommended for all generated emails and required for series slots." } }, "required": [ "recipientType", "from", "fromName", "subject" ] }, "SendEmailResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Message ID (for single sends) or batch ID (for batch sends)" }, "provider": { "type": "string" }, "status": { "type": "string", "description": "sent, queued, or processing" }, "sentCount": { "type": "integer" }, "message": { "type": "string" }, "sendId": { "type": "string", "description": "Real tracking id for a single send. Use it with the email metrics/logs endpoints and the activity view. Absent for batch sends." }, "batchId": { "type": "string", "description": "Batch id for an audience/tag send. Absent for single sends." }, "emailId": { "type": "string", "description": "Echoes the generated email id this send was tagged with, when provided. Use it to query this email's performance across every API send." }, "conversationId": { "type": "string", "description": "Conversation this send belongs to, when known." } } }, "EmailMetrics": { "type": "object", "description": "Aggregate performance for one generated email across every API send of it. Sourced from the tracking worker, so values may be slightly stale and cover roughly the last 30 days of raw send history (aggregates persist longer). Opens are directional: Apple Mail Privacy Protection and bots inflate them; clicks and delivery events are stronger signals.", "properties": { "summary": { "type": "object", "properties": { "totalEmails": { "type": "integer" }, "delivered": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "deliveryRate": { "type": "number", "description": "0-100." }, "openRate": { "type": "number", "description": "0-100. Directional \u2014 inflated by Apple Mail Privacy Protection and bots." }, "clickRate": { "type": "number", "description": "0-100." }, "bounceRate": { "type": "number", "description": "0-100." }, "complaintRate": { "type": "number", "description": "0-100." }, "unsubscribeRate": { "type": "number", "description": "0-100." } } }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" } } } }, "countryBreakdown": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "count": { "type": "integer" } } } }, "lastUpdated": { "type": "string", "format": "date-time", "description": "When these stats were last refreshed from the tracking worker." }, "cached": { "type": "boolean" } }, "required": [ "summary", "lastUpdated" ] }, "EmailSendLog": { "type": "object", "description": "A single per-recipient send row for one generated email, straight from the tracking worker's D1 table (snake_case fields). Rows are retained roughly 30 days.", "properties": { "id": { "type": "integer" }, "tracking_id": { "type": "string" }, "domain": { "type": "string" }, "from_email": { "type": "string" }, "to_email": { "type": "string" }, "subject": { "type": "string", "nullable": true }, "status": { "type": "string", "description": "sent, delivered, bounced, complained, or suppressed." }, "opened_at": { "type": "string", "nullable": true }, "clicked_at": { "type": "string", "nullable": true }, "open_count": { "type": "integer" }, "click_count": { "type": "integer" }, "bounce_type": { "type": "string", "nullable": true }, "complaint_type": { "type": "string", "nullable": true }, "created_at": { "type": "string" } } }, "ApiResponseEmailMetrics": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EmailMetrics" } } } ] }, "ApiResponseEmailLogs": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "emails": { "type": "array", "items": { "$ref": "#/components/schemas/EmailSendLog" } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } } } } ] }, "BatchStatus": { "type": "object", "properties": { "batchId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed" ] }, "recipientType": { "type": "string", "enum": [ "audience", "segment", "tag" ] }, "recipientId": { "type": "string" }, "provider": { "type": "string" }, "totalCount": { "type": "integer" }, "queuedCount": { "type": "integer" }, "sentCount": { "type": "integer" }, "failedCount": { "type": "integer" }, "from": { "type": "string" }, "fromName": { "type": "string" }, "subject": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true }, "error": { "type": "string", "nullable": true } } }, "ApiResponseSendEmail": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SendEmailResult" } } } ] }, "ApiResponseBatchStatus": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BatchStatus" } } } ] }, "SendingMetricsTotals": { "type": "object", "properties": { "sent": { "type": "integer", "minimum": 0 }, "delivered": { "type": "integer", "minimum": 0 }, "bounced": { "type": "integer", "minimum": 0 }, "complained": { "type": "integer", "minimum": 0 } }, "required": [ "sent", "delivered", "bounced", "complained" ] }, "SendingMetricsToday": { "type": "object", "properties": { "sent": { "type": "integer", "minimum": 0 }, "reserved": { "type": "integer", "minimum": 0 }, "dailyLimit": { "type": "integer", "minimum": 0 }, "remainingToday": { "type": "integer", "minimum": 0 } }, "required": [ "sent", "reserved", "dailyLimit", "remainingToday" ] }, "SendingMetricsHistoryPeriod": { "type": "object", "properties": { "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "description": "Monthly period in YYYY-MM format." }, "sent": { "type": "integer", "minimum": 0 }, "delivered": { "type": "integer", "minimum": 0 }, "bounced": { "type": "integer", "minimum": 0 }, "complained": { "type": "integer", "minimum": 0 } }, "required": [ "period", "sent", "delivered", "bounced", "complained" ] }, "SendingMetrics": { "type": "object", "properties": { "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "description": "Current monthly period in YYYY-MM format." }, "monthly": { "$ref": "#/components/schemas/SendingMetricsTotals" }, "today": { "$ref": "#/components/schemas/SendingMetricsToday" }, "monthlyLimit": { "type": "integer", "minimum": 0 }, "remainingMonth": { "type": "integer", "minimum": 0 }, "history": { "type": "array", "description": "Previous monthly periods. Returned only when the months query parameter is supplied.", "items": { "$ref": "#/components/schemas/SendingMetricsHistoryPeriod" } } }, "required": [ "period", "monthly", "today", "monthlyLimit", "remainingMonth" ] }, "ApiResponseSendingMetrics": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SendingMetrics" } } } ] }, "Campaign": { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "name": { "type": "string" }, "conversationId": { "type": "string" }, "emailId": { "type": "string", "nullable": true, "description": "Generated email ID when the campaign was created from a specific email." }, "subject": { "type": "string" }, "preheaderText": { "type": "string", "nullable": true }, "from": { "type": "string", "format": "email" }, "fromName": { "type": "string" }, "replyTo": { "type": "string", "nullable": true }, "recipientType": { "type": "string", "enum": [ "audience", "tag" ] }, "recipientId": { "type": "string", "description": "First segment or list ID. Always equals recipientIds[0] when recipientIds is set." }, "recipientIds": { "type": "array", "maxItems": 20, "items": { "type": "string" }, "description": "Segment or list IDs of the same type. Unique people across the selection receive one email. Omitted on single-recipient campaigns." }, "topicId": { "type": "string", "nullable": true }, "estimatedRecipients": { "type": "integer", "nullable": true }, "providerType": { "type": "string", "enum": [ "ses", "resend", "sendgrid", "mailgun", "migma" ] }, "variables": { "type": "object", "nullable": true, "additionalProperties": true }, "status": { "type": "string", "enum": [ "draft", "pending_review", "scheduled", "sending", "throttled", "sent", "failed", "cancelled" ] }, "scheduledAt": { "type": "string", "format": "date-time", "nullable": true }, "scheduledTimezone": { "type": "string", "nullable": true }, "batchId": { "type": "string", "nullable": true }, "sentAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "error": { "type": "string", "nullable": true }, "triggeredBy": { "type": "string", "enum": [ "manual", "api", "automation" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreateCampaignRequest": { "type": "object", "required": [ "projectId", "name", "conversationId", "from", "fromName", "recipientType", "recipientId" ], "properties": { "projectId": { "type": "string", "description": "Project ID" }, "name": { "type": "string", "description": "Campaign name" }, "conversationId": { "type": "string", "description": "Conversation ID that owns the generated email" }, "emailId": { "type": "string", "description": "Generated email ID from result.emails[].emailId. Recommended for series slots." }, "subject": { "type": "string", "description": "Email subject (auto-populated from conversation if omitted)" }, "preheaderText": { "type": "string", "description": "Preheader text" }, "from": { "type": "string", "format": "email", "description": "Sender email address" }, "fromName": { "type": "string", "description": "Sender display name" }, "replyTo": { "type": "string", "format": "email", "description": "Reply-to address" }, "recipientType": { "type": "string", "enum": [ "audience", "tag" ], "description": "Send to a segment (audience) or tag" }, "recipientId": { "type": "string", "description": "Segment or list ID. Required unless recipientIds is set. Ignored when recipientIds is present except as recipientIds[0] on the stored campaign." }, "recipientIds": { "type": "array", "maxItems": 20, "items": { "type": "string" }, "description": "Send to several segments or several lists of the same type. Unique people receive one email. Cannot mix segments and lists. Maximum 20." }, "topicId": { "type": "string", "description": "Topic ID for preference filtering" }, "providerType": { "type": "string", "enum": [ "ses", "resend", "sendgrid", "mailgun", "migma" ], "description": "Email provider (default: migma)" }, "variables": { "type": "object", "additionalProperties": true, "description": "Template variables" } } }, "ScheduleCampaignRequest": { "type": "object", "required": [ "scheduledAt" ], "properties": { "scheduledAt": { "type": "string", "format": "date-time", "description": "ISO 8601 datetime for sending" }, "scheduledTimezone": { "type": "string", "description": "IANA timezone (e.g. America/New_York). Defaults to UTC." } } }, "ApiResponseCampaign": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Campaign" } } } ] }, "ApiResponseListCampaigns": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } }, "total": { "type": "integer" } } } } } ] }, "CampaignStats": { "type": "object", "description": "Aggregate engagement stats for a campaign. Sourced from the tracking worker; may be cached and slightly stale.", "properties": { "totalSent": { "type": "integer" }, "totalDelivered": { "type": "integer" }, "uniqueOpens": { "type": "integer" }, "totalOpens": { "type": "integer" }, "uniqueClicks": { "type": "integer" }, "totalClicks": { "type": "integer" }, "unsubscribes": { "type": "integer" }, "bounces": { "type": "integer" }, "openRate": { "type": "number", "description": "Unique opens divided by delivered." }, "clickRate": { "type": "number", "description": "Unique clicks divided by delivered." }, "lastUpdated": { "type": "string", "format": "date-time", "description": "When these stats were last refreshed from the tracking worker." }, "botOpens": { "type": "integer", "description": "Opens attributed to bots or automated scanners, when detected." }, "botClicks": { "type": "integer", "description": "Clicks attributed to bots or automated scanners, when detected." }, "mppOpens": { "type": "integer", "description": "Opens attributed to Apple Mail Privacy Protection, when detected." }, "conversion": { "type": "object", "description": "Conversion outcomes attributed to this campaign (last click within five days, single credit). Omitted entirely when no conversion source has reported for the campaign; never returned as zeros. revenue is the signed net including refunds.", "properties": { "conversions": { "type": "integer", "description": "Count of attributed sales." }, "revenue": { "type": "number", "description": "Signed net revenue across sales, refunds, and chargebacks." }, "currency": { "type": "string", "nullable": true, "description": "ISO code when all entries share one currency, otherwise null." }, "source": { "type": "string", "enum": [ "connector", "api", "mixed" ] } } } }, "required": [ "totalSent", "totalDelivered", "uniqueOpens", "totalOpens", "uniqueClicks", "totalClicks", "unsubscribes", "bounces", "openRate", "clickRate", "lastUpdated" ] }, "ApiResponseCampaignStats": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CampaignStats" } } } ] }, "CampaignLog": { "type": "object", "description": "A per-recipient delivery and engagement record. Fields are tracking-worker (D1) columns in snake_case.", "properties": { "to_email": { "type": "string", "description": "Recipient email address." }, "subject": { "type": "string", "nullable": true, "description": "Subject line as sent." }, "status": { "type": "string", "description": "Delivery status, e.g. delivered, bounced, complained, suppressed." }, "opened_at": { "type": "string", "format": "date-time", "nullable": true, "description": "First open timestamp, or null if not opened." }, "clicked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "First click timestamp, or null if not clicked." }, "open_count": { "type": "integer", "description": "Number of recorded opens." }, "click_count": { "type": "integer", "description": "Number of recorded clicks." }, "bounce_type": { "type": "string", "nullable": true, "description": "Bounce classification when the row bounced, e.g. hard or soft." }, "complaint_type": { "type": "string", "nullable": true, "description": "Complaint classification when the recipient reported the message." }, "campaign_id": { "type": "string", "description": "Campaign this row belongs to." }, "created_at": { "type": "string", "format": "date-time", "description": "When the send was logged." } } }, "ApiResponseCampaignLogs": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "emails": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignLog" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Cursor for the next page, or null when there are no more rows." }, "hasMore": { "type": "boolean" } }, "required": [ "emails", "nextCursor", "hasMore" ] } } } ] }, "KnowledgeBaseEntry": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the entry" }, "title": { "type": "string", "description": "Title of the knowledge base entry" }, "content": { "type": "string", "description": "Content of the knowledge base entry" }, "date": { "type": "string", "format": "date-time", "description": "Creation date" } }, "required": [ "id", "title", "content" ] }, "ProjectImage": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "url" ] }, "AddImageRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "URL of the image" }, "description": { "type": "string", "maxLength": 1000, "description": "Optional description. If omitted, an AI-generated description is filled in asynchronously after upload." }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 10, "description": "Optional tags. If omitted, AI-generated tags are filled in asynchronously after upload." } }, "required": [ "url" ] }, "UpdateLogosRequest": { "type": "object", "properties": { "primary": { "type": "string", "format": "uri", "nullable": true, "description": "Primary logo URL (set to null to remove)" }, "secondary": { "type": "string", "format": "uri", "nullable": true, "description": "Secondary logo URL (set to null to remove)" }, "favicon": { "type": "string", "format": "uri", "nullable": true, "description": "Favicon URL (set to null to remove)" } }, "minProperties": 1 }, "UpdateImageRequest": { "type": "object", "description": "At least one of `description` or `tags` must be provided alongside `imageUrl`.", "properties": { "imageUrl": { "type": "string", "format": "uri", "description": "URL of the image to update" }, "description": { "type": "string", "maxLength": 1000, "description": "Updated description" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 10, "description": "Updated tags" } }, "required": [ "imageUrl" ], "anyOf": [ { "required": [ "description" ] }, { "required": [ "tags" ] } ] }, "UpdateKnowledgeBaseRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Updated title" }, "content": { "type": "string", "minLength": 1, "maxLength": 50000, "description": "Updated content" } }, "minProperties": 1 }, "AddKnowledgeBaseRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Title of the knowledge base entry" }, "content": { "type": "string", "minLength": 1, "maxLength": 50000, "description": "Content of the knowledge base entry" } }, "required": [ "title", "content" ] }, "EditEmailRequest": { "type": "object", "properties": { "prompt": { "type": "string", "description": "Natural-language edit request, e.g. \"Make this shorter and more transactional\"." }, "label": { "type": "string", "description": "Optional version label." } }, "required": [ "prompt" ] }, "GeneratedEmail": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "description": "Stable generated email ID. Use this to fetch, edit, export, test-send, or send one email." }, "emailId": { "type": [ "string", "null" ], "description": "Stable generated email ID. Same value as id." }, "conversationId": { "type": "string" }, "messageId": { "type": [ "string", "null" ] }, "slotIdx": { "type": "integer", "description": "Zero-based slot index in the generated series." }, "slot": { "type": "integer", "description": "One-based slot number for display." }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "html": { "type": "string", "description": "Production-ready email HTML for this email." }, "sendOffsetDays": { "type": "integer", "description": "Suggested send offset in days for series emails." }, "status": { "type": "string", "enum": [ "ready", "processing", "failed" ] }, "screenshotUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Rendered email screenshot URL when available." }, "thumbnailUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Alias of screenshotUrl when available." } }, "required": [ "id", "emailId", "conversationId", "messageId", "slotIdx", "slot", "subject", "preheader", "html", "status" ] }, "Email": { "type": "object", "properties": { "id": { "type": "string" }, "emailId": { "type": "string" }, "conversationId": { "type": "string" }, "messageId": { "type": [ "string", "null" ] }, "slotIdx": { "type": "integer" }, "slotUuid": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "html": { "type": "string", "description": "Production-ready email HTML." }, "screenshotUrl": { "type": [ "string", "null" ], "format": "uri" }, "thumbnailUrl": { "type": [ "string", "null" ], "format": "uri" }, "warnings": { "type": "array", "items": { "type": "string" } }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "emailId", "conversationId", "messageId", "slotIdx", "slotUuid", "status", "subject", "preheader", "html", "warnings", "thumbnailUrl", "updatedAt" ] }, "ApiResponseEmail": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Email" } } } ] }, "EventIdentifiers": { "type": "object", "description": "Contact identity for the event. At least one of email or subscriberId is required. Provider ids (externalCustomerId, externalCheckoutId, externalOrderId) support integrations and conversion attribution.", "properties": { "email": { "type": "string", "format": "email" }, "subscriberId": { "type": "string" }, "externalCustomerId": { "type": "string", "maxLength": 200 }, "externalCheckoutId": { "type": "string", "maxLength": 200 }, "externalOrderId": { "type": "string", "maxLength": 200, "description": "The provider's order or charge id. Required for the event to record a conversion." } } }, "EventProfile": { "type": "object", "description": "Contact metadata to update. Profile updates never change subscription status, tags, or consent. Events never opt a contact in.", "properties": { "firstName": { "type": "string", "maxLength": 120 }, "lastName": { "type": "string", "maxLength": 120 }, "phone": { "type": "string", "maxLength": 80 }, "country": { "type": "string", "maxLength": 80 }, "language": { "type": "string", "maxLength": 40 }, "customFields": { "type": "object", "additionalProperties": true } } }, "IngestEventRow": { "type": "object", "required": [ "name", "identifiers" ], "properties": { "name": { "type": "string", "maxLength": 120, "description": "Event name, e.g. purchase.completed. Names containing refund or cancelled record negative conversion amounts." }, "origin": { "type": "string", "maxLength": 80, "default": "api" }, "eventVersion": { "type": "string", "maxLength": 40 }, "identifiers": { "$ref": "#/components/schemas/EventIdentifiers" }, "profile": { "$ref": "#/components/schemas/EventProfile" }, "properties": { "type": "object", "additionalProperties": true, "description": "Event facts. Up to 16KB, 50 top-level keys, 4 levels deep. A numeric value (major units, e.g. 49.99) together with identifiers.externalOrderId records a conversion; currency is an ISO code, default USD." }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the event happened. Defaults to receipt time." }, "dedupeKey": { "type": "string", "maxLength": 200, "description": "Event-identity dedupe key. Replaying the same key stores nothing and returns the original eventId." } } }, "IngestEventRequest": { "type": "object", "required": [ "projectId", "name", "identifiers" ], "properties": { "projectId": { "type": "string" }, "name": { "type": "string", "maxLength": 120, "description": "Event name, e.g. purchase.completed. Names containing refund or cancelled record negative conversion amounts." }, "origin": { "type": "string", "maxLength": 80, "default": "api" }, "eventVersion": { "type": "string", "maxLength": 40 }, "identifiers": { "$ref": "#/components/schemas/EventIdentifiers" }, "profile": { "$ref": "#/components/schemas/EventProfile" }, "properties": { "type": "object", "additionalProperties": true, "description": "Event facts. Up to 16KB, 50 top-level keys, 4 levels deep. A numeric value (major units, e.g. 49.99) together with identifiers.externalOrderId records a conversion; currency is an ISO code, default USD." }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the event happened. Defaults to receipt time." }, "dedupeKey": { "type": "string", "maxLength": 200, "description": "Event-identity dedupe key. Replaying the same key stores nothing and returns the original eventId." } } }, "TrackEventResult": { "type": "object", "properties": { "stored": { "type": "boolean", "description": "false when the dedupeKey was seen before; eventId then refers to the original event." }, "eventId": { "type": "string" }, "dedupeKey": { "type": "string" } } }, "TrackEventBatchResult": { "type": "object", "properties": { "accepted": { "type": "integer" }, "duplicates": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "stored": { "type": "boolean" }, "eventId": { "type": "string" }, "dedupeKey": { "type": "string" } } } }, "invalid": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "error": { "type": "string" } } } } } }, "ApiResponseTrackEventResult": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TrackEventResult" } } } ] }, "ApiResponseTrackEventBatchResult": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TrackEventBatchResult" } } } ] }, "BillingCredits": { "type": "object", "properties": { "currentPlan": { "type": "string", "description": "The account's current plan" }, "isExpired": { "type": "boolean", "description": "Whether the current plan has expired" }, "planExpiry": { "type": "string", "description": "Date the current plan period ends (ISO 8601)" }, "hasCredits": { "type": "boolean", "description": "Whether the account has credits available right now" }, "emailCreditsRemainingToday": { "type": "number", "description": "Email generation credits remaining today" }, "imageCreditsRemainingToday": { "type": "number", "description": "Image generation credits remaining today" }, "monthlyCreditsRemaining": { "type": "number", "description": "Credits remaining in the current monthly period" } }, "required": [ "currentPlan", "isExpired", "planExpiry", "hasCredits", "emailCreditsRemainingToday", "imageCreditsRemainingToday", "monthlyCreditsRemaining" ] }, "ApiResponseBillingCredits": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BillingCredits" } } } ] }, "CreateUpgradeLinkRequest": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "basic", "premium", "business", "basic_annual", "premium_annual", "business_annual" ], "description": "Target plan for a checkout link. Omit to get a billing portal link for existing Stripe customers." } } }, "UpgradeLink": { "type": "object", "properties": { "url": { "type": "string", "description": "Link the account owner opens in a browser to upgrade or manage the subscription" }, "kind": { "type": "string", "enum": [ "checkout", "portal" ], "description": "Whether the link is a Stripe Checkout session or the billing portal" }, "sessionId": { "type": "string", "description": "Stripe Checkout session id, when kind is checkout" }, "orderId": { "type": "string", "description": "Migma order id associated with the checkout, when applicable" } }, "required": [ "url", "kind" ] }, "ApiResponseUpgradeLink": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UpgradeLink" } } } ] }, "DomainPurchaseQuote": { "type": "object", "properties": { "rootDomain": { "type": "string", "description": "The full domain, e.g. 'acme.com'" }, "tld": { "type": "string", "description": "The top-level domain, e.g. 'com'" }, "available": { "type": "boolean", "description": "Whether the domain is available to register" }, "supported": { "type": "boolean", "description": "Whether Migma supports registering this TLD" }, "premium": { "type": "boolean", "description": "Whether the registry marks this domain as premium" }, "sellPrice": { "type": "number", "description": "Yearly registration price" }, "currency": { "type": "string", "description": "Currency for sellPrice, e.g. 'USD'" } }, "required": [ "rootDomain", "tld" ] }, "DomainPurchaseSearchData": { "type": "object", "properties": { "quotes": { "type": "array", "items": { "$ref": "#/components/schemas/DomainPurchaseQuote" } } }, "required": [ "quotes" ] }, "ApiResponseDomainPurchaseSearch": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DomainPurchaseSearchData" } } } ] }, "PurchaseDomainRequest": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "minLength": 3, "maxLength": 253, "description": "The domain to purchase, e.g. 'acme.com'" }, "redirectUrl": { "type": "string", "format": "uri", "description": "Where to send the account owner after checkout completes" } } }, "DomainPurchaseStarted": { "type": "object", "properties": { "checkoutUrl": { "type": "string", "description": "Stripe checkout URL the account owner opens and pays in a browser" }, "checkoutSessionId": { "type": "string", "description": "Stripe Checkout session id, when applicable" }, "stripeInvoiceId": { "type": "string", "description": "Stripe invoice id, when applicable" }, "stripeSubscriptionId": { "type": "string", "description": "Stripe subscription id, when applicable" }, "billingMode": { "type": "string", "enum": [ "annual_subscription" ], "description": "How the domain is billed. Domains renew yearly." }, "updateApplied": { "type": "boolean", "description": "Whether the purchase was applied to an existing subscription" } }, "required": [ "checkoutUrl" ] }, "ApiResponseDomainPurchaseStarted": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DomainPurchaseStarted" } } } ] }, "DomainPurchaseRegistration": { "type": "object", "properties": { "id": { "type": "string", "description": "Registration id" }, "rootDomain": { "type": "string", "description": "The purchased domain" }, "status": { "type": "string", "enum": [ "payment_pending", "registering", "active", "failed", "refunded" ], "description": "Registration status. Moves from payment_pending to registering to active. Failed registrations are refunded." }, "sellPrice": { "type": "number", "description": "Yearly registration price paid" }, "currency": { "type": "string", "description": "Currency for sellPrice, e.g. 'USD'" } }, "required": [ "id", "rootDomain", "status" ] }, "DomainPurchaseRegistrationsData": { "type": "object", "properties": { "registrations": { "type": "array", "items": { "$ref": "#/components/schemas/DomainPurchaseRegistration" } } }, "required": [ "registrations" ] }, "ApiResponseDomainPurchaseRegistrations": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DomainPurchaseRegistrationsData" } } } ] }, "CustomDnsRecord": { "type": "object", "properties": { "id": { "type": "string", "description": "Record id, used to remove the record" }, "type": { "type": "string", "enum": [ "A", "AAAA", "CNAME", "MX", "TXT", "NS" ], "description": "DNS record type" }, "name": { "type": "string", "description": "Record name. '@' for the root domain, a label like 'mail', or a full name" }, "content": { "type": "string", "description": "Record value, e.g. an IP address, hostname, or TXT content" }, "priority": { "type": "number", "description": "Priority, set on MX records" }, "createdAt": { "type": "string", "description": "When the record was added (ISO 8601)" } }, "required": [ "id", "type", "name", "content", "createdAt" ] }, "DnsRecordsData": { "type": "object", "properties": { "managed": { "type": "boolean", "description": "Whether Migma hosts this domain's DNS zone. Only domains bought in Migma have Migma-hosted zones. When false, records is empty." }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/CustomDnsRecord" } } }, "required": [ "managed", "records" ] }, "ApiResponseDnsRecords": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DnsRecordsData" } } } ] }, "AddDnsRecordRequest": { "type": "object", "required": [ "name", "content" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Record name. '@' for the root domain, a label like 'mail', or a full name. Root and www are reserved for domain forwarding." }, "content": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "Record value, e.g. an IP address, hostname, or TXT content" }, "type": { "type": "string", "enum": [ "A", "AAAA", "CNAME", "MX", "TXT", "NS" ], "default": "TXT", "description": "DNS record type" }, "priority": { "type": "integer", "minimum": 0, "maximum": 65535, "description": "Priority for MX records" } } }, "DnsRecordCreatedData": { "type": "object", "properties": { "record": { "$ref": "#/components/schemas/CustomDnsRecord" } }, "required": [ "record" ] }, "ApiResponseDnsRecordCreated": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DnsRecordCreatedData" } } } ] }, "ApiResponseDnsRecordRemoved": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } ] } }, "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "API key authentication. Use 'Authorization: Bearer YOUR_API_KEY' where YOUR_API_KEY is obtained from the Migma dashboard under Settings \u2192 Developers \u2192 API Keys." } } } }