{ "openapi": "3.1.0", "info": { "title": "Mailmark API", "version": "1.0.0", "summary": "Email hosting, campaigns, and sending for your own domain.", "description": "Mailmark hosts email on domains you own: mailboxes, campaigns, follow-up sequences, warmup, and transactional sending.\n\nThe authenticated REST API is served from https://api.mailmark.dev and needs an API key (`dm_live_...`) as a bearer token. Domain-scoped keys reach every endpoint for their own domain; org-wide keys can read the analytics endpoints across all domains but cannot write.\n\nThe endpoints under https://www.mailmark.dev/api/tools are the free public tools and need no key. They are rate limited per IP.", "termsOfService": "https://www.mailmark.dev/terms", "contact": { "name": "Mailmark support", "email": "support@mailmark.dev", "url": "https://www.mailmark.dev/contact" } }, "externalDocs": { "description": "Mailmark API reference", "url": "https://www.mailmark.dev/docs/api" }, "servers": [ { "url": "https://api.mailmark.dev", "description": "Authenticated REST API" }, { "url": "https://www.mailmark.dev", "description": "Public tool endpoints (no API key)" } ], "tags": [ { "name": "Mailboxes", "description": "Email addresses on a verified domain." }, { "name": "Sender groups", "description": "Groups of mailboxes and addresses to send as." }, { "name": "Send", "description": "Transactional and campaign sending." }, { "name": "Emails", "description": "Stored email in a mailbox." }, { "name": "Contacts", "description": "The account's contact book." }, { "name": "Sequences", "description": "Automated multi-step follow-ups." }, { "name": "Analytics", "description": "Domain health, warmup, bounces, suppressions, campaign stats." }, { "name": "Tools", "description": "Free public tools on www.mailmark.dev." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/mailboxes": { "get": { "tags": [ "Mailboxes" ], "operationId": "listMailboxes", "summary": "List mailboxes", "description": "Returns every mailbox on the domain the API key is scoped to.", "responses": { "200": { "description": "The domain's mailboxes.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" } } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Mailboxes" ], "operationId": "createMailbox", "summary": "Create a mailbox", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMailboxRequest" } } } }, "responses": { "201": { "description": "The mailbox that was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mailbox" } } } }, "400": { "description": "Missing or malformed address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A mailbox with that address already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/mailboxes/{address}": { "delete": { "tags": [ "Mailboxes" ], "operationId": "deleteMailbox", "summary": "Delete a mailbox", "description": "Deletes the mailbox and every email stored in it. This cannot be undone.", "parameters": [ { "name": "address", "in": "path", "required": true, "description": "Local part or full address, e.g. `support` or `support@acme.com`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The mailbox was deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } } } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sender-groups": { "get": { "tags": [ "Sender groups" ], "operationId": "listSenderGroups", "summary": "List sender groups", "responses": { "200": { "description": "The domain's sender groups.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SenderGroup" } } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Sender groups" ], "operationId": "createSenderGroup", "summary": "Create a sender group", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSenderGroupRequest" } } } }, "responses": { "201": { "description": "The sender group that was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderGroup" } } } }, "400": { "description": "Missing name, or the group would have no mailboxes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sender-groups/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "tags": [ "Sender groups" ], "operationId": "updateSenderGroup", "summary": "Update a sender group", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSenderGroupRequest" } } } }, "responses": { "200": { "description": "The updated sender group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderGroup" } } } }, "400": { "description": "Malformed body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Sender groups" ], "operationId": "deleteSenderGroup", "summary": "Delete a sender group", "responses": { "200": { "description": "The group was deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } } } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/send": { "post": { "tags": [ "Send" ], "operationId": "sendEmail", "summary": "Send or schedule an email", "description": "`type: \"transactional\"` sends one email addressed to every recipient. `type: \"campaign\"` sends an individual email per recipient and returns a shared `batchId`. Pass `scheduledAt` (future Unix milliseconds) to schedule instead of sending now.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendRequest" } } } }, "responses": { "200": { "description": "The send was accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResult" } } } }, "400": { "description": "Missing required fields, or scheduledAt is not in the future.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Every recipient was refused by the send policy (suppressed, unsubscribed, or invalid). Permanent: do not retry unchanged.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "blocked": { "type": "array", "items": { "$ref": "#/components/schemas/BlockedRecipient" } } } } ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/emails": { "get": { "tags": [ "Emails" ], "operationId": "listEmails", "summary": "List emails in a mailbox folder", "parameters": [ { "name": "mailbox", "in": "query", "description": "Local part or full address. Defaults to the domain's first mailbox.", "schema": { "type": "string" } }, { "name": "folder", "in": "query", "schema": { "type": "string", "default": "inbox", "enum": [ "inbox", "sent", "outbox", "drafts", "trash" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "The emails in that folder.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EmailSummary" } } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/emails/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Emails" ], "operationId": "getEmail", "summary": "Fetch one email", "responses": { "200": { "description": "The email.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Emails" ], "operationId": "deleteEmail", "summary": "Trash or permanently delete an email", "description": "Moves the email to trash. An email already in trash is deleted permanently.", "responses": { "200": { "description": "The email was trashed or deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "moved": { "type": "string", "example": "trash" } } } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/contacts": { "get": { "tags": [ "Contacts" ], "operationId": "listContacts", "summary": "List contacts", "responses": { "200": { "description": "The account's contacts.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Contacts" ], "operationId": "createContact", "summary": "Create or update a contact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactRequest" } } } }, "responses": { "201": { "description": "The contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "description": "Missing email or name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/contacts/{id}": { "delete": { "tags": [ "Contacts" ], "operationId": "deleteContact", "summary": "Delete a contact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The contact was deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } } } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sequences": { "get": { "tags": [ "Sequences" ], "operationId": "listSequences", "summary": "List sequences with enrollment stats", "responses": { "200": { "description": "The domain's sequences.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Sequence" } } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Sequences" ], "operationId": "createSequence", "summary": "Create a sequence", "description": "The first step must be a `send_email` step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSequenceRequest" } } } }, "responses": { "201": { "description": "The sequence that was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sequence" } } } }, "400": { "description": "Malformed steps, or the first step is not send_email.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sequences/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "tags": [ "Sequences" ], "operationId": "updateSequenceStatus", "summary": "Pause or resume a sequence", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSequenceRequest" } } } }, "responses": { "200": { "description": "The new status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused" ] } } } } } }, "400": { "description": "`status` must be \"paused\" or \"active\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Sequences" ], "operationId": "cancelSequence", "summary": "Cancel a sequence", "description": "Cancels the sequence and every active enrollment on it.", "responses": { "200": { "description": "The sequence was cancelled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "example": "completed" }, "cancelledEnrollments": { "type": "integer" } } } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sequences/{id}/enroll": { "post": { "tags": [ "Sequences" ], "operationId": "enrollContacts", "summary": "Enroll contacts in a sequence", "description": "Up to 100 contacts per request. The sequence must be active.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollRequest" } } } }, "responses": { "200": { "description": "How many enrolled and how many were skipped.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enrolled": { "type": "integer" }, "skipped": { "type": "integer" }, "enrollmentIds": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "The sequence is not active, or the contacts array is empty or too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/domain-health": { "get": { "tags": [ "Analytics" ], "operationId": "getDomainHealth", "summary": "Latest domain health check", "description": "A domain-scoped key returns one object. An org-wide key returns one entry per domain.", "parameters": [ { "name": "domain", "in": "query", "description": "Filter to one domain (org-wide keys).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Domain health.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DomainHealth" }, { "type": "array", "items": { "$ref": "#/components/schemas/DomainHealth" } } ] } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/warmup": { "get": { "tags": [ "Analytics" ], "operationId": "getWarmupStatus", "summary": "Warmup status per mailbox", "parameters": [ { "name": "mailbox", "in": "query", "description": "Full address to filter to.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Warmup status.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WarmupStatus" } } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bounces": { "get": { "tags": [ "Analytics" ], "operationId": "getBounceStats", "summary": "Bounce and complaint rates", "parameters": [ { "name": "days", "in": "query", "description": "Lookback window in days.", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 90 } }, { "name": "domain", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bounce stats.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BounceStats" }, { "type": "array", "items": { "$ref": "#/components/schemas/BounceStats" } } ] } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/suppressions": { "get": { "tags": [ "Analytics" ], "operationId": "listSuppressions", "summary": "Unsubscribes and suppressed addresses", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 } }, { "name": "after", "in": "query", "description": "Unix millisecond timestamp to page from.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Suppression list.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SuppressionPage" }, { "type": "array", "items": { "$ref": "#/components/schemas/SuppressionPage" } } ] } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/campaign-stats": { "get": { "tags": [ "Analytics" ], "operationId": "getCampaignStats", "summary": "Sequence and batch campaign stats", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "default": "all", "enum": [ "all", "sequence", "batch" ] } }, { "name": "sequenceId", "in": "query", "schema": { "type": "string" } }, { "name": "batchId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Campaign stats.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignStats" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is valid but not scoped for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or it belongs to another domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/tools/check-deliverability": { "post": { "tags": [ "Tools" ], "operationId": "checkDeliverability", "summary": "Check a domain's SPF, DKIM, DMARC, MX and blacklist status", "security": [], "servers": [ { "url": "https://www.mailmark.dev" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckDeliverabilityRequest" } } } }, "responses": { "200": { "description": "The deliverability report.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Missing or malformed domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/tools/validate-emails": { "post": { "tags": [ "Tools" ], "operationId": "validateEmails", "summary": "Validate up to 100 email addresses", "security": [], "servers": [ { "url": "https://www.mailmark.dev" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateEmailsRequest" } } } }, "responses": { "200": { "description": "Per-address results and a summary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/EmailValidationResult" } }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "valid": { "type": "integer" }, "risky": { "type": "integer" }, "invalid": { "type": "integer" } } } } } } } }, "400": { "description": "Empty list, or more than 100 addresses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/tools/generate-subject-lines": { "post": { "tags": [ "Tools" ], "operationId": "generateSubjectLines", "summary": "Generate cold email subject lines", "security": [], "servers": [ { "url": "https://www.mailmark.dev" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateSubjectLinesRequest" } } } }, "responses": { "200": { "description": "Eight subject lines with an explanation each.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subjectLines": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "string" }, "tip": { "type": "string" } } } }, "generationsRemaining": { "type": "integer" } } } } } }, "400": { "description": "Missing industry, offer, or tone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Daily per-IP limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Generation is not configured on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A Mailmark API key (`dm_live_...`), created in Dashboard -> Developer. Domain-scoped keys reach every endpoint for their domain; org-wide keys can read the analytics endpoints across all domains but cannot write." } }, "schemas": { "Error": { "type": "object", "description": "Every error body. `error` is the human-readable message and is also repeated as `message`; `code` is the stable identifier to branch on.", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "example": "Unauthorized" }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "unprocessable_entity", "rate_limited", "internal_error", "service_unavailable", "upstream_error" ], "example": "unauthorized" }, "message": { "type": "string", "example": "Unauthorized" }, "hint": { "type": "string", "description": "What the caller can do to resolve the error.", "example": "Pass a valid API key as \"Authorization: Bearer dm_live_...\". Keys are created in Dashboard -> Developer." }, "status": { "type": "integer", "example": 401 }, "documentation_url": { "type": "string", "format": "uri", "example": "https://www.mailmark.dev/docs/api" } } }, "BlockedRecipient": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "reason": { "type": "string", "example": "invalid_address" }, "message": { "type": "string", "example": "invalid address" }, "detail": { "type": "string" } } }, "Mailbox": { "type": "object", "properties": { "id": { "type": "string" }, "address": { "type": "string", "example": "support" }, "fullAddress": { "type": "string", "example": "support@acme.com" }, "displayName": { "type": [ "string", "null" ], "example": "Support Team" } } }, "CreateMailboxRequest": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "description": "Local part only; the domain is appended automatically.", "example": "support" }, "displayName": { "type": "string", "example": "Support Team" } } }, "SenderGroup": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mailboxIds": { "type": "array", "items": { "type": "string" } }, "emails": { "type": "array", "items": { "type": "string", "format": "email" } } } }, "CreateSenderGroupRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "mailboxes": { "description": "`\"all\"`, or the mailbox addresses to include.", "oneOf": [ { "type": "string", "const": "all" }, { "type": "array", "items": { "type": "string" } } ], "default": "all" }, "emails": { "type": "array", "items": { "type": "string", "format": "email" } } } }, "UpdateSenderGroupRequest": { "type": "object", "properties": { "name": { "type": "string" }, "emails": { "type": "array", "items": { "type": "string", "format": "email" } }, "addEmails": { "type": "array", "items": { "type": "string", "format": "email" } }, "removeEmails": { "type": "array", "items": { "type": "string", "format": "email" } }, "mailboxes": { "oneOf": [ { "type": "string", "const": "all" }, { "type": "array", "items": { "type": "string" } } ] } } }, "SendRequest": { "type": "object", "required": [ "from", "to", "subject" ], "description": "At least one of `html` or `text` is required.", "properties": { "from": { "type": "string", "format": "email", "description": "A mailbox on the API key's domain.", "example": "hello@acme.com" }, "to": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" } } ] }, "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" }, "type": { "type": "string", "enum": [ "transactional", "campaign" ], "default": "transactional" }, "scheduledAt": { "type": "integer", "description": "Future Unix millisecond timestamp." } } }, "SendResult": { "type": "object", "properties": { "messageId": { "type": "string", "description": "Transactional sends." }, "messageIds": { "type": "array", "items": { "type": "string" }, "description": "Campaign sends, one per recipient." }, "batchId": { "type": "string", "description": "Campaign sends." }, "status": { "type": "string", "enum": [ "queued", "scheduled" ] }, "blocked": { "type": "array", "items": { "$ref": "#/components/schemas/BlockedRecipient" } } } }, "EmailSummary": { "type": "object", "properties": { "id": { "type": "string" }, "messageId": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "snippet": { "type": "string" }, "folder": { "type": "string" }, "date": { "type": "integer" }, "read": { "type": "boolean" }, "starred": { "type": "boolean" }, "hasAttachments": { "type": "boolean" }, "deliveryStatus": { "type": [ "string", "null" ] }, "openedAt": { "type": [ "integer", "null" ] }, "batchId": { "type": [ "string", "null" ] } } }, "Email": { "allOf": [ { "$ref": "#/components/schemas/EmailSummary" }, { "type": "object", "properties": { "cc": { "type": [ "array", "null" ], "items": { "type": "string" } }, "bcc": { "type": [ "array", "null" ], "items": { "type": "string" } }, "s3Key": { "type": "string" } } } ] }, "Contact": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" } } }, "CreateContactRequest": { "type": "object", "required": [ "email", "name" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" } } }, "SequenceStep": { "oneOf": [ { "type": "object", "required": [ "type", "subject", "html" ], "properties": { "type": { "type": "string", "const": "send_email" }, "subject": { "type": "string", "example": "Hey {{firstName}}" }, "html": { "type": "string" } } }, { "type": "object", "required": [ "type", "delayMs" ], "properties": { "type": { "type": "string", "const": "delay" }, "delayMs": { "type": "integer", "example": 86400000 } } } ] }, "Sequence": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "completed" ] }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceStep" } }, "mailboxAddress": { "type": [ "string", "null" ] }, "stats": { "type": "object" }, "createdAt": { "type": "integer" } } }, "CreateSequenceRequest": { "type": "object", "required": [ "name", "from", "steps" ], "properties": { "name": { "type": "string" }, "from": { "type": "string", "format": "email" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceStep" } } } }, "UpdateSequenceRequest": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "active", "paused" ] } } }, "EnrollRequest": { "type": "object", "required": [ "contacts" ], "properties": { "contacts": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "mergeFields": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "firstName": "Alice", "company": "Acme Corp" } } } } } } }, "DomainHealth": { "type": "object", "properties": { "domain": { "type": [ "string", "null" ] }, "checkedAt": { "type": [ "integer", "null" ] }, "overallScore": { "type": [ "integer", "null" ] }, "reputationStatus": { "type": [ "string", "null" ] }, "spf": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ] } } }, "dkim": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ] } } }, "dmarc": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ] } } }, "blacklisted": { "type": [ "boolean", "null" ] }, "blacklistEntries": { "type": "array", "items": { "type": "string" } }, "bounceRate": { "type": [ "number", "null" ] }, "complaintRate": { "type": [ "number", "null" ] } } }, "WarmupStatus": { "type": "object", "properties": { "mailbox": { "type": "string" }, "status": { "type": "string" }, "speed": { "type": "string", "enum": [ "slow", "normal", "fast" ] }, "currentDay": { "type": "integer" }, "dailyLimit": { "type": "integer" }, "sentToday": { "type": "integer" }, "receivedToday": { "type": "integer" }, "healthScore": { "type": "number" }, "inboxRate": { "type": "number" }, "startedAt": { "type": "integer" }, "lastActivityAt": { "type": [ "integer", "null" ] } } }, "BounceStats": { "type": "object", "properties": { "domain": { "type": [ "string", "null" ] }, "period": { "type": "object", "properties": { "days": { "type": "integer" }, "from": { "type": "integer" }, "to": { "type": "integer" } } }, "totalSent": { "type": "integer" }, "delivered": { "type": "integer" }, "bounced": { "type": "integer" }, "failed": { "type": "integer" }, "bounceRate": { "type": "number" }, "complaintRate": { "type": "number" } } }, "SuppressionPage": { "type": "object", "properties": { "domain": { "type": [ "string", "null" ] }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "unsubscribedAt": { "type": "integer" }, "source": { "type": "string", "example": "one-click" } } } } } }, "CampaignStats": { "type": "object", "properties": { "sequences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "stats": { "type": "object" } } } }, "batches": { "type": "array", "items": { "type": "object", "properties": { "batchId": { "type": "string" }, "sentAt": { "type": "integer" }, "stats": { "type": "object" } } } } } }, "CheckDeliverabilityRequest": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "example": "acme.com" } } }, "ValidateEmailsRequest": { "type": "object", "required": [ "emails" ], "properties": { "emails": { "type": "array", "maxItems": 100, "items": { "type": "string", "format": "email" } } } }, "EmailValidationResult": { "type": "object", "properties": { "email": { "type": "string" }, "status": { "type": "string", "enum": [ "valid", "risky", "invalid" ] }, "reason": { "type": "string" }, "checks": { "type": "object" } } }, "GenerateSubjectLinesRequest": { "type": "object", "required": [ "industry", "offer", "tone" ], "properties": { "industry": { "type": "string", "maxLength": 200, "example": "SaaS" }, "offer": { "type": "string", "maxLength": 200, "example": "a 15 minute demo" }, "tone": { "type": "string", "enum": [ "casual", "professional", "direct", "friendly", "urgent" ] } } } } } }