{ "openapi": "3.1.0", "info": { "title": "Mailumi Email API", "version": "1.0.0", "summary": "Send transactional email from your own domain, read delivery events and receive email.", "description": "JSON over HTTPS. Authenticate with a Mailumi API key in the Authorization header. Each key has permissions (email:send, email:read, domains:read, contacts:write), may be limited to one domain, and is limited to 120 requests per minute. Errors are JSON objects with a human-readable `error` and a machine-readable `code`. Deprecation policy: breaking changes only ship in a new version such as /api/v2, version 1 keeps working for at least 12 months after that, workspace owners get an email at least 6 months before an endpoint is retired, and deprecated endpoints return `Deprecation` and `Sunset` headers (https://mailumi.com/docs#versioning). Full guide: https://mailumi.com/docs. Everything in one Markdown file: https://mailumi.com/llms-full.txt.", "contact": { "name": "Mailumi support", "email": "support@mailumi.com", "url": "https://mailumi.com/contact" }, "termsOfService": "https://mailumi.com/terms" }, "servers": [ { "url": "https://mailumi.com/api/v1", "description": "Production" } ], "security": [ { "apiKey": [] } ], "externalDocs": { "description": "Mailumi API documentation", "url": "https://mailumi.com/docs" }, "tags": [ { "name": "Emails", "description": "Send, schedule, cancel and read email." }, { "name": "Domains", "description": "Domains and their DNS verification status." }, { "name": "Contacts", "description": "Audiences and the contacts your campaigns are sent to." } ], "paths": { "/emails": { "post": { "operationId": "sendEmail", "tags": [ "Emails" ], "summary": "Send an email", "description": "Queues one email for sending and returns it with status queued, or scheduled with scheduled_at. Each recipient counts as one email toward the plan. Requires email:send.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailRequest" } } } }, "responses": { "200": { "description": "The accepted email.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } } }, "400": { "description": "The request is invalid; the message explains what to fix.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The plan’s monthly or daily sending limit is reached.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The idempotency key was used with different content, the email can no longer be changed, or a campaign is being sent to the audience.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is too large: over 15 MB for email, or over 1 MB for a contact import.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A temporary problem. Retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listEmails", "tags": [ "Emails" ], "summary": "List sent and received email", "description": "Newest first, 50 per page. Requires email:read.", "parameters": [ { "name": "direction", "in": "query", "schema": { "enum": [ "outbound", "inbound" ] }, "description": "Only sent or only received email." }, { "name": "before", "in": "query", "schema": { "type": "string" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "One page of email.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailList" } } } }, "400": { "description": "The request is invalid; the message explains what to fix.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/emails/batch": { "post": { "operationId": "sendBatch", "tags": [ "Emails" ], "summary": "Send up to 100 emails", "description": "Accepts or rejects the whole batch: if one email is invalid or the plan limit would be exceeded, nothing is sent. Batch emails cannot have attachments or scheduled_at. Requires email:send.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/SendEmailRequest" } } } } }, "responses": { "200": { "description": "The IDs of the accepted emails, in request order.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } } } } } } } }, "400": { "description": "The request is invalid; the message explains what to fix.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The plan’s monthly or daily sending limit is reached.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The idempotency key was used with different content, the email can no longer be changed, or a campaign is being sent to the audience.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is too large: over 15 MB for email, or over 1 MB for a contact import.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A temporary problem. Retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/emails/{id}": { "get": { "operationId": "getEmail", "tags": [ "Emails" ], "summary": "Get an email with its delivery events", "description": "Returns the content, each recipient’s status, every event and attachment links. Requires email:read.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The email ID returned when it was sent or received.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The email.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDetail" } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The email, attachment, template, audience or contact was not found.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "rescheduleEmail", "tags": [ "Emails" ], "summary": "Change the send time of a scheduled email", "description": "Only scheduled emails that have not been sent can be changed. Requires email:send.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The email ID returned when it was sent or received.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scheduled_at" ], "properties": { "scheduled_at": { "type": "string", "description": "Send later, up to 30 days ahead: an ISO 8601 date or \"in 1 hour\", \"in 3 days\".", "examples": [ "2026-10-07T09:00:00Z", "in 1 hour" ] } } } } } }, "responses": { "200": { "description": "The rescheduled email.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } } }, "400": { "description": "The request is invalid; the message explains what to fix.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The email, attachment, template, audience or contact was not found.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The idempotency key was used with different content, the email can no longer be changed, or a campaign is being sent to the audience.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/emails/{id}/cancel": { "post": { "operationId": "cancelEmail", "tags": [ "Emails" ], "summary": "Cancel a scheduled email", "description": "Cancels a scheduled email that has not been sent and returns it to the plan allowance. Requires email:send.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The email ID returned when it was sent or received.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The canceled email.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "id", "status" ], "properties": { "object": { "const": "email" }, "id": { "type": "string" }, "status": { "const": "canceled" } } } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The email, attachment, template, audience or contact was not found.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The idempotency key was used with different content, the email can no longer be changed, or a campaign is being sent to the audience.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/emails/{id}/attachments/{index}": { "get": { "operationId": "getAttachment", "tags": [ "Emails" ], "summary": "Download an attachment", "description": "Downloads one attachment of a sent or received email. Requires email:read.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The email ID returned when it was sent or received.", "schema": { "type": "string" } }, { "name": "index", "in": "path", "required": true, "description": "The attachment id from GET /emails/{id}, starting at 0.", "schema": { "type": "string", "pattern": "^\\d{1,2}$" } } ], "responses": { "200": { "description": "The file.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The email, attachment, template, audience or contact was not found.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/domains": { "get": { "operationId": "listDomains", "tags": [ "Domains" ], "summary": "List domains and their verification status", "description": "Returns your domains with the DNS records to publish and whether each is verified. A key limited to one domain sees only that domain. Requires domains:read.", "responses": { "200": { "description": "Your domains.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } } } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/audiences": { "get": { "operationId": "listAudiences", "tags": [ "Contacts" ], "summary": "List audiences", "description": "Newest first, with contact counts. Requires contacts:write.", "responses": { "200": { "description": "Your audiences.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Audience" } } } } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createAudience", "tags": [ "Contacts" ], "summary": "Create an audience", "description": "A workspace can have up to 100 audiences. Requires contacts:write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 100 } } } } } }, "responses": { "200": { "description": "The new audience.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" } } } }, "400": { "description": "The request is invalid; the message explains what to fix.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/audiences/{id}": { "get": { "operationId": "getAudience", "tags": [ "Contacts" ], "summary": "Get an audience", "description": "Requires contacts:write.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audience ID, starting with aud_.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The audience.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The email, attachment, template, audience or contact was not found.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "renameAudience", "tags": [ "Contacts" ], "summary": "Rename an audience", "description": "Requires contacts:write.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audience ID, starting with aud_.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 100 } } } } } }, "responses": { "200": { "description": "The renamed audience.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" } } } }, "400": { "description": "The request is invalid; the message explains what to fix.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The email, attachment, template, audience or contact was not found.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteAudience", "tags": [ "Contacts" ], "summary": "Delete an audience and its contacts", "description": "Not possible while a campaign is being sent to it. Unsubscribes stay recorded in your other audiences. Requires contacts:write.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audience ID, starting with aud_.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The audience was deleted.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The email, attachment, template, audience or contact was not found.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The idempotency key was used with different content, the email can no longer be changed, or a campaign is being sent to the audience.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/audiences/{id}/contacts": { "get": { "operationId": "listContacts", "tags": [ "Contacts" ], "summary": "List contacts in an audience", "description": "Sorted by email address, 100 per page. Requires contacts:write.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audience ID, starting with aud_.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 100 }, "description": "Only contacts whose email or name contains this text." }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "One page of contacts.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as after to load the next page." } } } } } }, "400": { "description": "The request is invalid; the message explains what to fix.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The email, attachment, template, audience or contact was not found.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "addContacts", "tags": [ "Contacts" ], "summary": "Add one contact or import up to 1,000", "description": "Send one contact object to get the contact back, or an array of up to 1,000 to get an import summary. Existing addresses get their names updated. Importing never resubscribes anyone: an address that unsubscribed anywhere in the workspace is added as unsubscribed. An audience holds up to 100,000 contacts. Requires contacts:write.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audience ID, starting with aud_.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/NewContact" }, { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/NewContact" } } ] } } } }, "responses": { "200": { "description": "The contact, or the import summary for an array.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Contact" }, { "$ref": "#/components/schemas/ContactImport" } ] } } } }, "400": { "description": "The request is invalid; the message explains what to fix.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The email, attachment, template, audience or contact was not found.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is too large: over 15 MB for email, or over 1 MB for a contact import.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/audiences/{id}/contacts/{contact}": { "get": { "operationId": "getContact", "tags": [ "Contacts" ], "summary": "Get a contact", "description": "Requires contacts:write.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audience ID, starting with aud_.", "schema": { "type": "string" } }, { "name": "contact", "in": "path", "required": true, "description": "The contact ID (con_…) or the contact’s email address, URL-encoded.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The contact.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The email, attachment, template, audience or contact was not found.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateContact", "tags": [ "Contacts" ], "summary": "Update or unsubscribe a contact", "description": "Changing unsubscribed applies to the address in every audience of the workspace. Only resubscribe people who asked for it. Requires contacts:write.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audience ID, starting with aud_.", "schema": { "type": "string" } }, { "name": "contact", "in": "path", "required": true, "description": "The contact ID (con_…) or the contact’s email address, URL-encoded.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "maxLength": 100 }, "last_name": { "type": "string", "maxLength": 100 }, "unsubscribed": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "The updated contact.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "description": "The request is invalid; the message explains what to fix.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The email, attachment, template, audience or contact was not found.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteContact", "tags": [ "Contacts" ], "summary": "Remove a contact from an audience", "description": "Requires contacts:write.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audience ID, starting with aud_.", "schema": { "type": "string" } }, { "name": "contact", "in": "path", "required": true, "description": "The contact ID (con_…) or the contact’s email address, URL-encoded.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The contact was removed.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The email, attachment, template, audience or contact was not found.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "mlu_live_…", "description": "A Mailumi API key from Dashboard → API keys. Use it only in server-side code." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A stable key (1–256 characters) for each logical email. Repeating a request with the same key within 24 hours returns the original result instead of sending again.", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "headers": { "RateLimit-Limit": { "description": "Requests allowed per minute for this key.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the limit resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "responses": { "400": { "description": "The request is invalid; the message explains what to fix.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The plan’s monthly or daily sending limit is reached.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the permission, the domain is not verified, or the key may not use this domain.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The email, attachment, template, audience or contact was not found.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The idempotency key was used with different content, the email can no longer be changed, or a campaign is being sent to the audience.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is too large: over 15 MB for email, or over 1 MB for a contact import.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests in one minute for this key, or more than 30 requests with an invalid key from one IP address. Wait for the number of seconds in Retry-After.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "An unexpected error. Nothing was confirmed; retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A temporary problem. Retry with the same Idempotency-Key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "description": "What went wrong and how to fix it." }, "code": { "enum": [ "invalid_request", "unauthorized", "plan_limit_reached", "forbidden", "not_found", "method_not_allowed", "conflict", "payload_too_large", "rate_limited", "internal_error", "service_unavailable" ], "description": "Machine-readable error code." } }, "examples": [ { "error": "Send to no more than 50 recipients per email.", "code": "invalid_request" } ] }, "Attachment": { "type": "object", "required": [ "filename", "content" ], "properties": { "filename": { "type": "string" }, "content": { "type": "string", "contentEncoding": "base64", "description": "The file, base64 encoded." }, "content_type": { "type": "string", "examples": [ "application/pdf" ] }, "content_id": { "type": "string", "description": "Show the file inline in HTML with ." } } }, "Tag": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" }, "value": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" } } }, "SendEmailRequest": { "type": "object", "required": [ "from", "to" ], "additionalProperties": false, "description": "Provide subject plus html and/or text, or template_id with variables.", "properties": { "from": { "type": "string", "description": "Sender. The domain must be verified in your Mailumi account.", "examples": [ "Acme " ] }, "to": { "oneOf": [ { "type": "string", "description": "An email address, optionally with a name: \"Acme \".", "examples": [ "Acme " ] }, { "type": "array", "items": { "type": "string", "description": "An email address, optionally with a name: \"Acme \".", "examples": [ "Acme " ] }, "maxItems": 50 } ], "description": "One or more recipients. to, cc and bcc together allow 50 addresses." }, "cc": { "oneOf": [ { "type": "string", "description": "An email address, optionally with a name: \"Acme \".", "examples": [ "Acme " ] }, { "type": "array", "items": { "type": "string", "description": "An email address, optionally with a name: \"Acme \".", "examples": [ "Acme " ] }, "maxItems": 50 } ] }, "bcc": { "oneOf": [ { "type": "string", "description": "An email address, optionally with a name: \"Acme \".", "examples": [ "Acme " ] }, { "type": "array", "items": { "type": "string", "description": "An email address, optionally with a name: \"Acme \".", "examples": [ "Acme " ] }, "maxItems": 50 } ] }, "reply_to": { "oneOf": [ { "type": "string", "description": "An email address, optionally with a name: \"Acme \".", "examples": [ "Acme " ] }, { "type": "array", "items": { "type": "string", "description": "An email address, optionally with a name: \"Acme \".", "examples": [ "Acme " ] }, "maxItems": 10 } ] }, "subject": { "type": "string", "maxLength": 998, "description": "Subject line without line breaks. Optional with template_id." }, "html": { "type": "string", "description": "HTML body. html and text together are at most 500 KB." }, "text": { "type": "string", "description": "Plain-text body." }, "attachments": { "type": "array", "maxItems": 20, "description": "Up to 20 files, 10 MB in total.", "items": { "$ref": "#/components/schemas/Attachment" } }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Extra headers, for example List-Unsubscribe." }, "tags": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/Tag" } }, "scheduled_at": { "type": "string", "description": "Send later, up to 30 days ahead: an ISO 8601 date or \"in 1 hour\", \"in 3 days\".", "examples": [ "2026-10-07T09:00:00Z", "in 1 hour" ] }, "template_id": { "type": "string", "pattern": "^tpl_[a-f0-9]{32}$", "description": "Send a template saved in Dashboard → Templates instead of subject and html." }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Values for the template placeholders; they are HTML-escaped." } } }, "Email": { "type": "object", "required": [ "id", "object", "direction", "from", "to", "subject", "status", "created_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "email" }, "domain_id": { "type": "string" }, "direction": { "enum": [ "outbound", "inbound" ] }, "from": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "status": { "type": "string", "description": "For example queued, scheduled, sent, delivered, bounced, complained, failed, canceled or received." }, "last_event": { "type": "string" }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "tags": { "type": "object", "additionalProperties": { "type": "string" } }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "EmailDetail": { "allOf": [ { "$ref": "#/components/schemas/Email" }, { "type": "object", "properties": { "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "reply_to": { "type": "array", "items": { "type": "string" } }, "text": { "type": "string" }, "html": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "content_deleted": { "type": "boolean", "description": "True once the content and attachments were deleted, 30 days after the email was sent or received." }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "recipient": { "type": "string" }, "kind": { "enum": [ "to", "cc", "bcc" ] }, "status": { "type": "string" } } } }, "events": { "type": "array", "items": { "type": "object", "required": [ "type", "created_at" ], "properties": { "type": { "type": "string", "examples": [ "email.delivered" ] }, "recipient": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "content_id": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "download_url": { "type": "string" } } } } } } ] }, "EmailList": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Email" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as before to load the next page." } } }, "DnsRecord": { "type": "object", "required": [ "purpose", "required", "type", "name", "value", "verified" ], "properties": { "purpose": { "enum": [ "ownership", "dkim", "mail_from", "dmarc", "receiving" ] }, "required": { "type": "boolean" }, "type": { "enum": [ "TXT", "CNAME", "MX" ] }, "name": { "type": "string" }, "value": { "type": "string" }, "priority": { "type": "integer" }, "verified": { "type": "boolean" } } }, "Domain": { "type": "object", "required": [ "id", "name", "sendingStatus", "records" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ownershipVerified": { "type": "boolean" }, "sendingEnabled": { "type": "boolean" }, "receivingEnabled": { "type": "boolean" }, "openTracking": { "type": "boolean" }, "clickTracking": { "type": "boolean" }, "sendingStatus": { "type": "string", "examples": [ "pending", "verified" ] }, "receivingStatus": { "type": "string", "examples": [ "disabled", "pending", "verified" ] }, "lastChecked": { "type": [ "integer", "null" ], "description": "Milliseconds since 1970." }, "createdAt": { "type": "integer", "description": "Milliseconds since 1970." }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/DnsRecord" } } } }, "Audience": { "type": "object", "required": [ "object", "id", "name", "contacts", "subscribed", "created_at" ], "properties": { "object": { "const": "audience" }, "id": { "type": "string", "examples": [ "aud_4f0c2b9e8d7a4c1b9e3f5a6d7c8b9a0e" ] }, "name": { "type": "string" }, "contacts": { "type": "integer" }, "subscribed": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "NewContact": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "first_name": { "type": "string", "maxLength": 100 }, "last_name": { "type": "string", "maxLength": 100 }, "unsubscribed": { "type": "boolean", "description": "Add the contact as unsubscribed." } } }, "Contact": { "type": "object", "required": [ "object", "id", "audience_id", "email", "unsubscribed", "created_at" ], "properties": { "object": { "const": "contact" }, "id": { "type": "string" }, "audience_id": { "type": "string" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "unsubscribed": { "type": "boolean" }, "unsubscribed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ContactImport": { "type": "object", "required": [ "object", "audience_id", "added", "updated", "invalid" ], "properties": { "object": { "const": "import" }, "audience_id": { "type": "string" }, "added": { "type": "integer" }, "updated": { "type": "integer", "description": "Addresses that were already in the audience." }, "invalid": { "type": "array", "description": "Entries that were skipped.", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "email": { "type": "string" }, "error": { "type": "string" } } } } } }, "Deleted": { "type": "object", "required": [ "object", "id", "deleted" ], "properties": { "object": { "type": "string" }, "id": { "type": "string" }, "deleted": { "const": true } } } } } }