{ "x-doc-structure": { "resources": { "allowlists": { "title": "Allowlists", "description": "Add, list, or delete from your Rejection Allowlist.", "paths": [ "/allowlists/add", "/allowlists/list", "/allowlists/delete" ] }, "exports": { "title": "Exports", "description": "Start an export, or get information on export jobs in progress.", "paths": [ "/exports/info", "/exports/list", "/exports/rejects", "/exports/whitelist", "/exports/allowlist", "/exports/activity" ] }, "inbound": { "title": "Inbound", "description": "Manage your inbound domains and routes.", "paths": [ "/inbound/domains", "/inbound/add-domain", "/inbound/check-domain", "/inbound/delete-domain", "/inbound/routes", "/inbound/add-route", "/inbound/update-route", "/inbound/delete-route", "/inbound/send-raw" ] }, "ips": { "title": "IPs", "description": "Request and manage Dedicated IPs for your account, and set up reverse DNS.", "paths": [ "/ips/list", "/ips/info", "/ips/provision", "/ips/start-warmup", "/ips/cancel-warmup", "/ips/set-pool", "/ips/delete", "/ips/list-pools", "/ips/pool-info", "/ips/create-pool", "/ips/delete-pool", "/ips/check-custom-dns", "/ips/set-custom-dns" ] }, "messages": { "title": "Messages", "description": "Send, schedule, or get information on your emails.", "paths": [ "/messages/send", "/messages/send-sms", "/messages/send-template", "/messages/send-mc-template", "/messages/search", "/messages/search-time-series", "/messages/info", "/messages/content", "/messages/parse", "/messages/send-raw", "/messages/list-scheduled", "/messages/cancel-scheduled", "/messages/reschedule" ] }, "metadata": { "title": "Metadata", "description": "Manage your custom metadata fields in your account.", "paths": [ "/metadata/list", "/metadata/add", "/metadata/update", "/metadata/delete" ] }, "rejects": { "title": "Rejects", "description": "Add, list, or delete from your Rejection Denylist.", "paths": [ "/rejects/add", "/rejects/add-sms", "/rejects/delete", "/rejects/delete-sms", "/rejects/list", "/rejects/list-sms" ] }, "senders": { "title": "Senders", "description": "Manage or get information about your sending domains.", "paths": [ "/senders/list", "/senders/domains", "/senders/add-domain", "/senders/delete-domain", "/senders/check-domain", "/senders/verify-domain", "/senders/info", "/senders/time-series" ] }, "subaccounts": { "title": "Subaccounts", "description": "Manage your subaccounts, including the abilitiy to pause and resume sending.", "paths": [ "/subaccounts/list", "/subaccounts/add", "/subaccounts/info", "/subaccounts/update", "/subaccounts/delete", "/subaccounts/pause", "/subaccounts/resume" ] }, "tags": { "title": "Tags", "description": "List, delete, or get information on your Tags and their sending statistics.", "paths": [ "/tags/list", "/tags/delete", "/tags/info", "/tags/time-series", "/tags/all-time-series" ] }, "templates": { "title": "Templates", "description": "Manage templates created via the Mandrill UI or through the /templates endpoint.", "paths": [ "/templates/add", "/templates/info", "/templates/update", "/templates/publish", "/templates/delete", "/templates/list", "/templates/time-series", "/templates/render" ] }, "mctemplates": { "title": "Templates (MC)", "description": "Manage templates created via the Mailchimp UI.", "paths": [ "/mctemplates/info", "/mctemplates/list", "/mctemplates/time-series", "/mctemplates/render" ] }, "urls": { "title": "URLs", "description": "Manage your tracking domains.", "paths": [ "/urls/add-tracking-domain", "/urls/check-tracking-domain", "/urls/delete-tracking-domain", "/urls/tracking-domains" ] }, "users": { "title": "Users", "description": "Get information about your account, or ping Transactional.", "paths": [ "/users/info", "/users/ping", "/users/ping2", "/users/senders" ] }, "webhooks": { "title": "Webhooks", "description": "Manage the webhooks in your account.", "paths": [ "/webhooks/list", "/webhooks/add", "/webhooks/info", "/webhooks/update", "/webhooks/delete" ] } } }, "swagger": "2.0", "info": { "version": "1.4.1", "title": "Mailchimp Transactional API", "contact": { "name": "API Support", "email": "apihelp@mailchimp.com" }, "x-permalink": "https://github.com/mailchimp/mailchimp-client-lib-codegen/blob/main/spec/transactional.openapi.json" }, "host": "mandrillapp.com", "basePath": "/api/1.3", "schemes": [ "https" ], "consumes": [ "application/json" ], "produces": [ "application/json", "application/x-php", "application/x-yaml; charset=utf-8" ], "paths": { "/allowlists/add": { "post": { "x-custom-config": { "methodNameCamel": "add", "methodNameSnake": "add" }, "summary": "Add email to allowlist", "description": "Adds an email to your email rejection allowlist. If the address is currently on your denylist, that denylist entry will be removed automatically.", "operationId": "postAllowlistsAdd", "tags": [ "allowlists" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "email" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "email": { "type": "string", "description": "an email address to add to the allowlist", "format": "email" }, "comment": { "type": "string", "description": "an optional description of why the email was added to the allowlist", "maxLength": 255 } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "a status object containing the address and the result of the operation", "properties": { "email": { "type": "string", "description": "the email address you provided", "example": "user@example.com" }, "added": { "type": "boolean", "description": "whether the operation succeeded", "example": true } } } } }, "deprecated": false } }, "/allowlists/list": { "post": { "x-custom-config": { "methodNameCamel": "list", "methodNameSnake": "list" }, "summary": "List allowlisted emails", "description": "Retrieves your email rejection allowlist. You can provide an email address or search prefix to limit the results. Returns up to 1000 results.", "operationId": "postAllowlistsList", "tags": [ "allowlists" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "email": { "type": "string", "description": "an optional email address or prefix to search by", "format": "email" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "up to 1000 allowlist entries", "items": { "type": "object", "description": "the information for each allowlist entry", "properties": { "email": { "type": "string", "format": "email", "description": "the email that is allowlisted", "example": "user@example.com" }, "detail": { "type": "string", "description": "a description of why the email was allowlisted", "example": "Added manually via the API" }, "created_at": { "type": "string", "format": "date-time", "description": "when the email was added to the allowlist", "example": "2025-04-29 18:47:35" } } } } } }, "deprecated": false } }, "/allowlists/delete": { "post": { "x-custom-config": { "methodNameCamel": "delete", "methodNameSnake": "delete" }, "summary": "Remove email from allowlist", "description": "Removes an email address from the allowlist.", "operationId": "postAllowlistsDelete", "tags": [ "allowlists" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "email" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "email": { "type": "string", "description": "the email address to remove from the allowlist", "format": "email" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "a status object containing the address and whether the deletion succeeded", "properties": { "email": { "type": "string", "description": "the email address that was removed from the denylist", "example": "user@example.com" }, "deleted": { "type": "boolean", "description": "whether the address was deleted successfully", "example": true } } } } }, "deprecated": false } }, "/exports/info": { "post": { "x-custom-config": { "methodNameCamel": "info", "methodNameSnake": "info" }, "summary": "View export info", "description": "Returns information about an export job. If the export job's state is 'complete', the returned data will include a URL you can use to fetch the results. Every export job produces a zip archive, but the format of the archive is distinct for each job type. The api calls that initiate exports include more details about the output format for that job type.", "operationId": "postExportsInfo", "tags": [ "exports" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "id" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "id": { "type": "string", "description": "an export job identifier" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the information about the export", "properties": { "id": { "type": "string", "description": "the unique identifier for this Export. Use this identifier when checking the export job's status", "example": "2025-04-29 18:48:05.63771" }, "created_at": { "type": "string", "description": "the date and time that the export job was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "format": "date-time", "example": "2025-04-29 18:48:05" }, "type": { "type": "string", "description": "the type of the export job - activity, reject, or allowlist", "example": "reject" }, "finished_at": { "type": "string", "description": "the date and time that the export job was finished as a UTC string in YYYY-MM-DD HH:MM:SS format", "format": "date-time", "example": "2025-04-29 18:58:10" }, "state": { "type": "string", "description": "the export job's state - waiting, working, complete, error, or expired.", "example": "complete" }, "result_url": { "type": "string", "description": "the url for the export job's results, if the job is completed.", "example": "https://s3-us-west-2.amazonaws.com/exports.mandrillapp.com/123456/activity-2025-04-29_18%3A31%3A05.zip" } } } } }, "deprecated": false } }, "/exports/list": { "post": { "x-custom-config": { "methodNameCamel": "list", "methodNameSnake": "list" }, "summary": "List exports", "description": "Returns a list of your exports.", "operationId": "postExportsList", "tags": [ "exports" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "the account's exports", "items": { "type": "object", "description": "the individual export info", "properties": { "id": { "type": "string", "description": "the unique identifier for this Export. Use this identifier when checking the export job's status", "example": "2025-04-29 18:48:05.63771" }, "created_at": { "type": "string", "description": "the date and time that the export job was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "format": "date-time", "example": "2025-04-29 18:48:05" }, "type": { "type": "string", "description": "the type of the export job - activity, reject, or allowlist", "example": "allowlist" }, "finished_at": { "type": "string", "description": "the date and time that the export job was finished as a UTC string in YYYY-MM-DD HH:MM:SS format", "format": "date-time", "example": "2025-04-29 18:58:10" }, "state": { "type": "string", "description": "the export job's state - waiting, working, complete, error, or expired.", "example": "complete" }, "result_url": { "type": "string", "description": "the url for the export job's results, if the job is completed.", "example": "https://s3-us-west-2.amazonaws.com/exports.mandrillapp.com/123456/allowlist-2025-04-29_18%3A31%3A05.zip" } } } } } }, "deprecated": false } }, "/exports/rejects": { "post": { "x-custom-config": { "methodNameCamel": "rejects", "methodNameSnake": "rejects" }, "summary": "Export denylist", "description": "Begins an export of your rejection denylist. The denylist will be exported to a zip archive containing a single file named rejects.csv that includes the following fields: email, reason, detail, created_at, expires_at, last_event_at, expires_at.", "operationId": "postExportsRejects", "tags": [ "exports" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "notify_email": { "type": "string", "description": "an optional email address to notify when the export job has finished.", "format": "email" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "information about the rejects export job that was started", "properties": { "id": { "type": "string", "description": "the unique identifier for this Export. Use this identifier when checking the export job's status", "example": "2025-04-29 18:48:05.63771" }, "created_at": { "type": "string", "description": "the date and time that the export job was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "format": "date-time", "example": "2025-04-29 18:48:05" }, "type": { "type": "string", "description": "the type of the export job - activity, reject, or whitelist", "example": "reject" }, "finished_at": { "type": "string", "description": "the date and time that the export job was finished as a UTC string in YYYY-MM-DD HH:MM:SS format", "format": "date-time", "example": "2025-04-29 18:58:10" }, "state": { "type": "string", "description": "the export job's state - waiting, working, complete, error, or expired.", "example": "waiting" }, "result_url": { "type": "string", "description": "the url for the export job's results, if the job is completed.", "example": "null" } } } } }, "deprecated": false } }, "/exports/whitelist": { "post": { "x-custom-config": { "methodNameCamel": "whitelist", "methodNameSnake": "whitelist" }, "summary": "Export Allowlist", "description": "Begins an export of your rejection allowlist. The allowlist will be exported to a zip archive containing a single file named allowlist.csv that includes the following fields: email, detail, created_at.", "operationId": "postExportsWhitelist", "tags": [ "exports" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "notify_email": { "type": "string", "description": "an optional email address to notify when the export job has finished.", "format": "email" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "information about the allowlist export job that was started", "properties": { "id": { "type": "string", "description": "the unique identifier for this Export. Use this identifier when checking the export job's status", "example": "2025-04-29 18:48:05.63771" }, "created_at": { "type": "string", "description": "the date and time that the export job was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "format": "date-time", "example": "2025-04-29 18:48:05" }, "type": { "type": "string", "description": "the type of the export job", "example": "allowlist" }, "finished_at": { "type": "string", "description": "the date and time that the export job was finished as a UTC string in YYYY-MM-DD HH:MM:SS format, or null for jobs that have not run", "format": "date-time", "example": "null" }, "state": { "type": "string", "description": "the export job's state", "example": "waiting" }, "result_url": { "type": "string", "description": "the url for the export job's results, if the job is complete", "example": "null" } } } } }, "deprecated": false } }, "/exports/allowlist": { "post": { "x-custom-config": { "methodNameCamel": "allowlist", "methodNameSnake": "allowlist" }, "summary": "Export Allowlist", "description": "Begins an export of your rejection allowlist. The allowlist will be exported to a zip archive containing a single file named allowlist.csv that includes the following fields: email, detail, created_at.", "operationId": "postExportsAllowlist", "tags": [ "exports" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "notify_email": { "type": "string", "description": "an optional email address to notify when the export job has finished.", "format": "email" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "information about the allowlist export job that was started", "properties": { "id": { "type": "string", "description": "the unique identifier for this Export. Use this identifier when checking the export job's status", "example": "2025-04-29 18:48:05.63771" }, "created_at": { "type": "string", "description": "the date and time that the export job was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "format": "date-time", "example": "2025-04-29 18:48:05" }, "type": { "type": "string", "description": "the type of the export job", "example": "allowlist" }, "finished_at": { "type": "string", "description": "the date and time that the export job was finished as a UTC string in YYYY-MM-DD HH:MM:SS format, or null for jobs that have not run", "format": "date-time", "example": "null" }, "state": { "type": "string", "description": "the export job's state", "example": "waiting" }, "result_url": { "type": "string", "description": "the url for the export job's results, if the job is complete", "example": "null" } } } } }, "deprecated": false } }, "/exports/activity": { "post": { "x-custom-config": { "methodNameCamel": "activity", "methodNameSnake": "activity" }, "summary": "Export activity history", "description": "Begins an export of your activity history. The activity will be exported to a zip archive containing a single file named activity.csv in the same format as you would be able to export from your account's activity view. It includes the following fields: Date, Email Address, Sender, Subject, Status, Tags, Opens, Clicks, Bounce Detail. If you have configured any custom metadata fields, they will be included in the exported data.", "operationId": "postExportsActivity", "tags": [ "exports" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "notify_email": { "type": "string", "description": "an optional email address to notify when the export job has finished", "format": "email" }, "date_from": { "type": "string", "description": "start date as a UTC string in YYYY-MM-DD HH:MM:SS format", "format": "date-time" }, "date_to": { "type": "string", "description": "end date as a UTC string in YYYY-MM-DD HH:MM:SS format", "format": "date-time" }, "tags": { "type": "array", "description": "an array of tag names to narrow the export to; will match messages that contain ANY of the tags", "items": { "type": "string", "description": "a tag name" } }, "senders": { "type": "array", "description": "an array of senders to narrow the export to", "items": { "type": "string", "description": "a sender address" } }, "states": { "type": "array", "description": "an array of message states to narrow the export to; messages with ANY of the states will be included", "items": { "type": "string", "description": "a message state", "enum": [ "sent", "rejected", "bounced", "soft-bounced", "spam", "unsub" ] } }, "api_keys": { "type": "array", "description": "an array of api keys to narrow the export to; messsagse sent with ANY of the keys will be included", "items": { "type": "string", "description": "an API key associated with your account" } } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "information about the activity export job that was started", "properties": { "id": { "type": "string", "description": "the unique identifier for this Export. Use this identifier when checking the export job's status", "example": "2025-04-29 18:48:05.63771" }, "created_at": { "type": "string", "description": "the date and time that the export job was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "format": "date-time", "example": "2025-04-29 18:48:05" }, "type": { "type": "string", "description": "the type of the export job", "example": "activity" }, "finished_at": { "type": "string", "description": "the date and time that the export job was finished as a UTC string in YYYY-MM-DD HH:MM:SS format, or null for jobs that have not run", "format": "date-time", "example": "2025-04-29 18:48:05" }, "state": { "type": "string", "description": "the export job's state", "example": "complete" }, "result_url": { "type": "string", "description": "the url for the export job's results, if the job is complete", "example": "https://s3-us-west-2.amazonaws.com/exports.mandrillapp.com/123456/activity-2025-04-29_18%3A31%3A05.zip" } } } } }, "deprecated": false } }, "/inbound/domains": { "post": { "x-custom-config": { "methodNameCamel": "domains", "methodNameSnake": "domains" }, "summary": "List inbound domains", "description": "List the domains that have been configured for inbound delivery.", "operationId": "postInboundDomains", "tags": [ "inbound" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "the inbound domains associated with the account", "items": { "type": "object", "description": "the individual domain info", "properties": { "domain": { "type": "string", "description": "the domain name that is accepting mail", "example": "https://intuit.com" }, "created_at": { "type": "string", "description": "the date and time that the inbound domain was added as a UTC string in YYYY-MM-DD HH:MM:SS format", "format": "date-time", "example": "2025-04-29 18:47:35" }, "valid_mx": { "type": "boolean", "description": "true if this inbound domain has successfully set up an MX record to deliver mail to the Mandrill servers", "example": true } } } } } }, "deprecated": false } }, "/inbound/add-domain": { "post": { "x-custom-config": { "methodNameCamel": "addDomain", "methodNameSnake": "add_domain" }, "summary": "Add inbound domain", "description": "Add an inbound domain to your account.", "operationId": "postInboundAddDomain", "tags": [ "inbound" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "domain" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "domain": { "type": "string", "description": "a domain name; Validation: strip_tags, required" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "information about the domain", "properties": { "domain": { "type": "string", "description": "the domain name that is accepting mail", "example": "https://intuit.com" }, "created_at": { "type": "string", "description": "the date and time that the inbound domain was added as a UTC string in YYYY-MM-DD HH:MM:SS format", "format": "date-time", "example": "2025-04-29 18:47:35" }, "valid_mx": { "type": "boolean", "description": "true if this inbound domain has successfully set up an MX record to deliver mail to the Mandrill servers", "example": true } } } } }, "deprecated": false } }, "/inbound/check-domain": { "post": { "x-custom-config": { "methodNameCamel": "checkDomain", "methodNameSnake": "check_domain" }, "summary": "Check domain settings", "description": "Check the MX settings for an inbound domain. The domain must have already been added with the add-domain call.", "operationId": "postInboundCheckDomain", "tags": [ "inbound" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "domain" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "domain": { "type": "string", "description": "an existing inbound domain" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "information about the inbound domain", "properties": { "domain": { "type": "string", "description": "the domain name that is accepting mail", "example": "https://intuit.com" }, "created_at": { "type": "string", "description": "the date and time that the inbound domain was added as a UTC string in YYYY-MM-DD HH:MM:SS format", "format": "date-time", "example": "2025-04-29 18:47:35" }, "valid_mx": { "type": "boolean", "description": "true if this inbound domain has successfully set up an MX record to deliver mail to the Mandrill servers", "example": true } } } } }, "deprecated": false } }, "/inbound/delete-domain": { "post": { "x-custom-config": { "methodNameCamel": "deleteDomain", "methodNameSnake": "delete_domain" }, "summary": "Delete inbound domain", "description": "Delete an inbound domain from the account. All mail will stop routing for this domain immediately.", "operationId": "postInboundDeleteDomain", "tags": [ "inbound" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "domain" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "domain": { "type": "string", "description": "an existing inbound domain" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "information about the deleted domain", "properties": { "domain": { "type": "string", "description": "the domain name that is accepting mail", "example": "https://intuit.com" }, "created_at": { "type": "string", "description": "the date and time that the inbound domain was added as a UTC string in YYYY-MM-DD HH:MM:SS format", "format": "date-time", "example": "2025-04-29 18:47:35" }, "valid_mx": { "type": "boolean", "description": "true if this inbound domain has successfully set up an MX record to deliver mail to the Mandrill servers", "example": true } } } } }, "deprecated": false } }, "/inbound/routes": { "post": { "x-custom-config": { "methodNameCamel": "routes", "methodNameSnake": "routes" }, "summary": "List routes", "description": "List the routes defined for an inbound domain or SMS program. Provide either domain or phone (not both).", "operationId": "postInboundRoutes", "tags": [ "inbound" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "domain": { "type": "string", "description": "The domain to check (required if phone is not provided)" }, "phone": { "type": "string", "description": "The SMS program phone number (required if domain is not provided)" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "the routes associated with the domain", "items": { "type": "object", "description": "the individual mailbox route", "properties": { "id": { "type": "string", "description": "the unique identifier of the route", "example": "12.123456" }, "pattern": { "type": "string", "description": "the search pattern that the mailbox name should match", "example": ".*" }, "url": { "type": "string", "description": "the webhook URL where inbound messages will be published", "example": "https://mydomain.com/webhook" } } } } } }, "deprecated": false } }, "/inbound/add-route": { "post": { "x-custom-config": { "methodNameCamel": "addRoute", "methodNameSnake": "add_route" }, "summary": "Add route", "description": "Add a new route to an inbound domain or SMS program. Provide either domain or phone (not both).", "operationId": "postInboundAddRoute", "tags": [ "inbound" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "url" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "domain": { "type": "string", "description": "An existing inbound domain (required if phone is not provided)" }, "phone": { "description": "The SMS program phone number - the TO number that receives inbound SMS (required if domain is not provided)", "type": "string" }, "pattern": { "type": "string", "description": "For email: the mailbox pattern (e.g., \"mailbox-*\"). For SMS: not used, the phone number is the pattern." }, "url": { "type": "string", "description": "the webhook URL where the inbound messages will be published" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the added mailbox route information", "properties": { "id": { "type": "string", "description": "the unique identifier of the route", "example": "12.123456" }, "pattern": { "type": "string", "description": "the search pattern that the mailbox name should match", "example": ".*" }, "url": { "type": "string", "description": "the webhook URL where inbound messages will be published", "example": "https://mydomain.com/webhook" } } } } }, "deprecated": false } }, "/inbound/update-route": { "post": { "x-custom-config": { "methodNameCamel": "updateRoute", "methodNameSnake": "update_route" }, "summary": "Update mailbox route", "description": "Update the pattern or webhook of an existing inbound mailbox route. If null is provided for any fields, the values will remain unchanged.", "operationId": "postInboundUpdateRoute", "tags": [ "inbound" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "id" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "id": { "type": "string", "description": "the unique identifier of an existing mailbox route" }, "pattern": { "type": "string", "description": "For email: The search pattern that the mailbox name should match. For SMS: the sender's phone number (FROM number). Null to leave unchanged" }, "url": { "type": "string", "description": "the webhook URL where the inbound messages will be published; Validation: webhookexists" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the updated mailbox route information", "properties": { "id": { "type": "string", "description": "the unique identifier of the route", "example": "12.123456" }, "pattern": { "type": "string", "description": "the search pattern that the mailbox name should match", "example": ".*" }, "url": { "type": "string", "description": "the webhook URL where inbound messages will be published", "example": "https://mydomain.com/webhook" } } } } }, "deprecated": false } }, "/inbound/delete-route": { "post": { "x-custom-config": { "methodNameCamel": "deleteRoute", "methodNameSnake": "delete_route" }, "summary": "Delete mailbox route", "description": "Delete an existing inbound mailbox route.", "operationId": "postInboundDeleteRoute", "tags": [ "inbound" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "id" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "id": { "type": "string", "description": "the unique identifier of an existing route" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the deleted mailbox route information", "properties": { "id": { "type": "string", "description": "the unique identifier of the route", "example": "12.123456" }, "pattern": { "type": "string", "description": "the search pattern that the mailbox name should match", "example": ".*" }, "url": { "type": "string", "description": "the webhook URL where inbound messages will be published", "example": "https://mydomain.com/webhook" } } } } }, "deprecated": false } }, "/inbound/send-raw": { "post": { "x-custom-config": { "methodNameCamel": "sendRaw", "methodNameSnake": "send_raw" }, "summary": "Send mime document", "description": "Take a raw MIME document destined for a domain with inbound domains set up, and send it to the inbound hook exactly as if it had been sent over SMTP.", "operationId": "postInboundSendRaw", "tags": [ "inbound" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "raw_message" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "raw_message": { "type": "string", "description": "the full MIME document of an email message" }, "to": { "type": "array", "description": "optionally define the recipients to receive the message - otherwise we'll use the To, Cc, and Bcc headers provided in the document", "items": { "type": "string", "description": "the email address of the recipient", "format": "email" } }, "mail_from": { "type": "string", "description": "the address specified in the MAIL FROM stage of the SMTP conversation. Required for the SPF check.", "format": "email" }, "helo": { "type": "string", "description": "the identification provided by the client mta in the MTA state of the SMTP conversation. Required for the SPF check." }, "client_address": { "type": "string", "description": "the remote MTA's ip address. Optional; required for the SPF check." } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "an array of the information for each recipient in the message (usually one) that matched an inbound route", "items": { "type": "object", "description": "the individual recipient information", "properties": { "email": { "type": "string", "description": "the email address of the matching recipient", "example": "user@example.com" }, "pattern": { "type": "string", "description": "the mailbox route pattern that the recipient matched", "example": ".*" }, "url": { "type": "string", "description": "the webhook URL that the message was posted to", "example": "https://mydomain.com/webhook" } } } } } }, "deprecated": false } }, "/ips/list": { "post": { "x-custom-config": { "methodNameCamel": "list", "methodNameSnake": "list" }, "summary": "List ip addresses", "description": "Lists your dedicated IPs.", "operationId": "postIpsList", "tags": [ "ips" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "an array of objects for each dedicated IP", "items": { "type": "object", "description": "information about a single dedicated IP", "properties": { "ip": { "type": "string", "description": "the ip address", "example": "123.123.123.123" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 18:47:35" }, "pool": { "type": "string", "description": "the name of the pool that this dedicated IP belongs to", "example": "Main Pool" }, "domain": { "type": "string", "description": "the domain name (reverse dns) of this dedicated IP", "example": "example.com" }, "custom_dns": { "type": "object", "description": "information about the ip's custom dns, if it has been configured", "properties": { "enabled": { "type": "boolean", "description": "a boolean indicating whether custom dns has been configured for this ip", "example": true }, "valid": { "type": "boolean", "description": "whether the ip's custom dns is currently valid", "example": true }, "error": { "type": "string", "description": "if the ip's custom dns is invalid, this will include details about the error", "example": "Invalid reverse DNS" } } }, "warmup": { "type": "object", "description": "information about the ip's warmup status", "properties": { "warming_up": { "type": "boolean", "description": "whether the ip is currently in warmup mode", "example": false }, "start_at": { "type": "string", "format": "date-time", "description": "the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-25 12:00:00" }, "end_at": { "type": "string", "format": "date-time", "description": "the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:00:00" } } } } } } } }, "deprecated": false } }, "/ips/info": { "post": { "x-custom-config": { "methodNameCamel": "info", "methodNameSnake": "info" }, "summary": "Get ip info", "description": "Retrieves information about a single dedicated IP.", "operationId": "postIpsInfo", "tags": [ "ips" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "ip": { "type": "string", "description": "a dedicated IP address" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "Information about the dedicated ip", "properties": { "ip": { "type": "string", "description": "the ip address", "example": "123.123.123.123" }, "created_at": { "type": "string", "description": "the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "format": "date-time", "example": "2025-04-29 18:47:35" }, "pool": { "type": "string", "description": "the name of the pool that this dedicated IP belongs to", "example": "Main Pool" }, "domain": { "type": "string", "description": "the domain name (reverse dns) of this dedicated IP", "example": "example.com" }, "custom_dns": { "type": "object", "description": "information about the ip's custom dns, if it has been configured", "properties": { "enabled": { "type": "boolean", "description": "a boolean indicating whether custom dns has been configured for this ip", "example": true }, "valid": { "type": "boolean", "description": "whether the ip's custom dns is currently valid", "example": true }, "error": { "type": "string", "description": "if the ip's custom dns is invalid, this will include details about the error", "example": "Invalid reverse DNS" } } }, "warmup": { "type": "object", "description": "information about the ip's warmup status", "properties": { "warming_up": { "type": "boolean", "description": "whether the ip is currently in warmup mode", "example": false }, "start_at": { "type": "string", "format": "date-time", "description": "the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-25 12:00:00" }, "end_at": { "type": "string", "format": "date-time", "description": "the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-05-25 12:00:00" } } } } } } }, "deprecated": false } }, "/ips/provision": { "post": { "x-custom-config": { "methodNameCamel": "provision", "methodNameSnake": "provision" }, "summary": "Request additional ip", "description": "Requests an additional dedicated IP for your account. Accounts may have one outstanding request at any time, and provisioning requests are processed within 24 hours.", "operationId": "postIpsProvision", "tags": [ "ips" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "warmup": { "type": "boolean", "description": "whether to enable warmup mode for the ip" }, "pool": { "type": "string", "description": "the id of the pool to add the dedicated ip to, or null to use your account's default pool" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "a description of the provisioning request that was created", "properties": { "requested_at": { "type": "string", "format": "date-time", "description": "the date and time that the request was created as a UTC timestamp in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 18:47:35" } } } } }, "deprecated": false } }, "/ips/start-warmup": { "post": { "x-custom-config": { "methodNameCamel": "startWarmup", "methodNameSnake": "start_warmup" }, "summary": "Start ip warmup", "description": "Begins the warmup process for a dedicated IP. During the warmup process, the Transactional API will gradually increase the percentage of your mail that is sent over the warming-up IP, over a period of roughly 30 days. The rest of your mail will be sent over shared IPs or other dedicated IPs in the same pool.", "operationId": "postIpsStartWarmup", "tags": [ "ips" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "ip" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "ip": { "type": "string", "description": "a dedicated ip address" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "Information about the dedicated IP", "properties": { "ip": { "type": "string", "description": "the ip address", "example": "123.123.123.123" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 18:47:35" }, "pool": { "type": "string", "description": "the name of the pool that this dedicated IP belongs to", "example": "Main Pool" }, "domain": { "type": "string", "description": "the domain name (reverse dns) of this dedicated IP", "example": "example.com" }, "custom_dns": { "type": "object", "description": "information about the ip's custom dns, if it has been configured", "properties": { "enabled": { "type": "boolean", "description": "a boolean indicating whether custom dns has been configured for this ip", "example": true }, "valid": { "type": "boolean", "description": "whether the ip's custom dns is currently valid", "example": true }, "error": { "type": "string", "description": "if the ip's custom dns is invalid, this will include details about the error", "example": "Invalid reverse DNS" } } }, "warmup": { "type": "object", "description": "information about the ip's warmup status", "properties": { "warming_up": { "type": "boolean", "description": "whether the ip is currently in warmup mode", "example": true }, "start_at": { "type": "string", "format": "date-time", "description": "the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-25 12:00:00" }, "end_at": { "type": "string", "format": "date-time", "description": "the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-05-25 12:00:00" } } } } } } }, "deprecated": false } }, "/ips/cancel-warmup": { "post": { "x-custom-config": { "methodNameCamel": "cancelWarmup", "methodNameSnake": "cancel_warmup" }, "summary": "Cancel ip warmup", "description": "Cancels the warmup process for a dedicated IP.", "operationId": "postIpsCancelWarmup", "tags": [ "ips" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "ip" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "ip": { "type": "string", "description": "a dedicated ip address" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "Information about the dedicated IP", "properties": { "ip": { "type": "string", "description": "the ip address", "example": "123.123.123.123" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 18:47:35" }, "pool": { "type": "string", "description": "the name of the pool that this dedicated IP belongs to", "example": "Main Pool" }, "domain": { "type": "string", "description": "the domain name (reverse dns) of this dedicated IP", "example": "example.com" }, "custom_dns": { "type": "object", "description": "information about the ip's custom dns, if it has been configured", "properties": { "enabled": { "type": "boolean", "description": "a boolean indicating whether custom dns has been configured for this ip", "example": true }, "valid": { "type": "boolean", "description": "whether the ip's custom dns is currently valid", "example": true }, "error": { "type": "string", "description": "if the ip's custom dns is invalid, this will include details about the error", "example": "Invalid reverse DNS" } } }, "warmup": { "type": "object", "description": "information about the ip's warmup status", "properties": { "warming_up": { "type": "boolean", "description": "whether the ip is currently in warmup mode", "example": false }, "start_at": { "type": "string", "format": "date-time", "description": "the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-25 12:00:00" }, "end_at": { "type": "string", "format": "date-time", "description": "the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-05-25 12:00:00" } } } } } } }, "deprecated": false } }, "/ips/set-pool": { "post": { "x-custom-config": { "methodNameCamel": "setPool", "methodNameSnake": "set_pool" }, "summary": "Move ip to different pool", "description": "Moves a dedicated IP to a different pool.", "operationId": "postIpsSetPool", "tags": [ "ips" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "ip", "pool" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "ip": { "type": "string", "description": "a dedicated ip address" }, "pool": { "type": "string", "description": "the name of the new pool to add the dedicated ip to" }, "create_pool": { "type": "boolean", "description": "whether to create the pool if it does not exist; if false and the pool does not exist, an Unknown_Pool will be thrown." } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "Information about the updated state of the dedicated IP", "properties": { "ip": { "type": "string", "description": "the ip address", "example": "123.123.123.123" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 18:47:35" }, "pool": { "type": "string", "description": "the name of the pool that this dedicated IP belongs to", "example": "Main Pool" }, "domain": { "type": "string", "description": "the domain name (reverse dns) of this dedicated IP", "example": "example.com" }, "custom_dns": { "type": "object", "description": "information about the ip's custom dns, if it has been configured", "properties": { "enabled": { "type": "boolean", "description": "a boolean indicating whether custom dns has been configured for this ip", "example": true }, "valid": { "type": "boolean", "description": "whether the ip's custom dns is currently valid", "example": true }, "error": { "type": "string", "description": "if the ip's custom dns is invalid, this will include details about the error", "example": "Invalid reverse DNS" } } }, "warmup": { "type": "object", "description": "information about the ip's warmup status", "properties": { "warming_up": { "type": "boolean", "description": "whether the ip is currently in warmup mode", "example": false }, "start_at": { "type": "string", "format": "date-time", "description": "the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-25 12:00:00" }, "end_at": { "type": "string", "format": "date-time", "description": "the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-05-25 12:00:00" } } } } } } }, "deprecated": false } }, "/ips/delete": { "post": { "x-custom-config": { "methodNameCamel": "delete", "methodNameSnake": "delete" }, "summary": "Delete ip address", "description": "Deletes a dedicated IP. This is permanent and cannot be undone.", "operationId": "postIpsDelete", "tags": [ "ips" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "ip" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "ip": { "type": "string", "description": "the dedicated ip to remove from your account" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "a description of the ip that was removed from your account.", "properties": { "ip": { "type": "string", "description": "the ip address", "example": "123.123.123.123" }, "deleted": { "type": "string", "description": "a boolean indicating whether the ip was successfully deleted", "example": true } } } } }, "deprecated": false } }, "/ips/list-pools": { "post": { "x-custom-config": { "methodNameCamel": "listPools", "methodNameSnake": "list_pools" }, "summary": "List ip pools", "description": "Lists your dedicated IP pools.", "operationId": "postIpsListPools", "tags": [ "ips" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "the dedicated IP pools for your account, up to a maximum of 1,000", "items": { "type": "object", "description": "information about each dedicated IP pool", "properties": { "name": { "type": "string", "description": "this pool's name", "example": "Main Pool" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that this pool was created as a UTC timestamp in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 18:47:35" }, "ips": { "type": "array", "description": "the dedicated IPs in this pool", "items": { "type": "object", "description": "information about each dedicated IP", "properties": { "ip": { "type": "string", "description": "the ip address", "example": "123.123.123.123" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-30 12:00:00" }, "pool": { "type": "string", "description": "the name of the pool that this dedicated IP belongs to", "example": "Main Pool" }, "domain": { "type": "string", "description": "the domain name (reverse dns) of this dedicated IP", "example": "example.com" }, "custom_dns": { "type": "object", "description": "information about the ip's custom dns, if it has been configured", "properties": { "enabled": { "type": "boolean", "description": "a boolean indicating whether custom dns has been configured for this ip", "example": true }, "valid": { "type": "boolean", "description": "whether the ip's custom dns is currently valid", "example": true }, "error": { "type": "string", "description": "if the ip's custom dns is invalid, this will include details about the error", "example": "Invalid reverse DNS" } } }, "warmup": { "type": "object", "description": "information about the ip's warmup status", "properties": { "warming_up": { "type": "boolean", "description": "whether the ip is currently in warmup mode", "example": false }, "start_at": { "type": "string", "format": "date-time", "description": "the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-25 12:00:00" }, "end_at": { "type": "string", "format": "date-time", "description": "the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-30 12:00:00" } } } } } } } } } } }, "deprecated": false } }, "/ips/pool-info": { "post": { "x-custom-config": { "methodNameCamel": "poolInfo", "methodNameSnake": "pool_info" }, "summary": "Get ip pool info", "description": "Describes a single dedicated IP pool.", "operationId": "postIpsPoolInfo", "tags": [ "ips" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "pool" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "pool": { "type": "string", "description": "a pool name" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "Information about the dedicated ip pool", "properties": { "name": { "type": "string", "description": "this pool's name", "example": "Main Pool" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that this pool was created as a UTC timestamp in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 18:47:35" }, "ips": { "type": "array", "description": "the dedicated IPs in this pool", "items": { "type": "object", "description": "information about each dedicated IP", "properties": { "ip": { "type": "string", "description": "the ip address", "example": "123.123.123.123" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-30 12:00:00" }, "pool": { "type": "string", "description": "the name of the pool that this dedicated IP belongs to", "example": "Main Pool" }, "domain": { "type": "string", "description": "the domain name (reverse dns) of this dedicated IP", "example": "example.com" }, "custom_dns": { "type": "object", "description": "information about the ip's custom dns, if it has been configured", "properties": { "enabled": { "type": "boolean", "description": "a boolean indicating whether custom dns has been configured for this ip", "example": true }, "valid": { "type": "boolean", "description": "whether the ip's custom dns is currently valid", "example": true }, "error": { "type": "string", "description": "if the ip's custom dns is invalid, this will include details about the error", "example": "Invalid reverse DNS" } } }, "warmup": { "type": "object", "description": "information about the ip's warmup status", "properties": { "warming_up": { "type": "boolean", "description": "whether the ip is currently in warmup mode", "example": false }, "start_at": { "type": "string", "format": "date-time", "description": "the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-25 12:00:00" }, "end_at": { "type": "string", "format": "date-time", "description": "the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-30 12:00:00" } } } } } } } } } }, "deprecated": false } }, "/ips/create-pool": { "post": { "x-custom-config": { "methodNameCamel": "createPool", "methodNameSnake": "create_pool" }, "summary": "Add ip pool", "description": "Creates a pool and returns it. If a pool already exists with this name, no action will be performed.", "operationId": "postIpsCreatePool", "tags": [ "ips" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "pool" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "pool": { "type": "string", "description": "the name of a pool to create" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "Information about the dedicated ip pool", "properties": { "name": { "type": "string", "description": "this pool's name", "example": "Main Pool" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that this pool was created as a UTC timestamp in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 18:47:35" }, "ips": { "type": "array", "description": "the dedicated IPs in this pool", "items": { "type": "object", "description": "information about each dedicated IP", "properties": { "ip": { "type": "string", "description": "the ip address", "example": "123.123.123.123" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-30 12:00:00" }, "pool": { "type": "string", "description": "the name of the pool that this dedicated IP belongs to", "example": "Main Pool" }, "domain": { "type": "string", "description": "the domain name (reverse dns) of this dedicated IP", "example": "example.com" }, "custom_dns": { "type": "object", "description": "information about the ip's custom dns, if it has been configured", "properties": { "enabled": { "type": "boolean", "description": "a boolean indicating whether custom dns has been configured for this ip", "example": true }, "valid": { "type": "boolean", "description": "whether the ip's custom dns is currently valid", "example": true }, "error": { "type": "string", "description": "if the ip's custom dns is invalid, this will include details about the error", "example": "Invalid reverse DNS" } } }, "warmup": { "type": "object", "description": "information about the ip's warmup status", "properties": { "warming_up": { "type": "boolean", "description": "whether the ip is currently in warmup mode", "example": false }, "start_at": { "type": "string", "format": "date-time", "description": "the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-25 12:00:00" }, "end_at": { "type": "string", "format": "date-time", "description": "the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-30 12:00:00" } } } } } } } } } }, "deprecated": false } }, "/ips/delete-pool": { "post": { "x-custom-config": { "methodNameCamel": "deletePool", "methodNameSnake": "delete_pool" }, "summary": "Delete ip pool", "description": "Deletes a pool. A pool must be empty before you can delete it, and you cannot delete your default pool.", "operationId": "postIpsDeletePool", "tags": [ "ips" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "pool" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "pool": { "type": "string", "description": "the name of the pool to delete" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "information about the status of the pool that was deleted", "properties": { "pool": { "type": "string", "description": "the name of the pool", "example": "Main Pool" }, "deleted": { "type": "boolean", "description": "whether the pool was deleted", "example": true } } } } }, "deprecated": false } }, "/ips/check-custom-dns": { "post": { "x-custom-config": { "methodNameCamel": "checkCustomDns", "methodNameSnake": "check_custom_dns" }, "summary": "Test custom dns", "description": "Tests whether a domain name is valid for use as the custom reverse DNS for a dedicated IP.", "operationId": "postIpsCheckCustomDns", "tags": [ "ips" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "ip", "domain" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "ip": { "type": "string", "description": "a dedicated ip address" }, "domain": { "type": "string", "description": "the domain name to test" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "information about the dedicated IP's new configuration", "properties": { "valid": { "type": "string", "description": "whether the domain name has a correctly-configured A record pointing to the ip address", "example": false }, "error": { "type": "string", "description": "if valid is false, this will contain details about why the domain's A record is incorrect", "example": "No A record found" } } } } }, "deprecated": false } }, "/ips/set-custom-dns": { "post": { "x-custom-config": { "methodNameCamel": "setCustomDns", "methodNameSnake": "set_custom_dns" }, "summary": "Set custom dns", "description": "Configures the custom DNS name for a dedicated IP.", "operationId": "postIpsSetCustomDns", "tags": [ "ips" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "ip", "domain" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "ip": { "type": "string", "description": "a dedicated ip address" }, "domain": { "type": "string", "description": "a domain name to set as the dedicated IP's custom dns name." } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "information about the dedicated IP's new configuration", "properties": { "ip": { "type": "string", "description": "the ip address", "example": "123.123.123.123" }, "created_at": { "type": "string", "description": "the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "format": "date-time", "example": "2025-04-30 12:00:00" }, "pool": { "type": "string", "description": "the name of the pool that this dedicated IP belongs to", "example": "Main Pool" }, "domain": { "type": "string", "description": "the domain name (reverse dns) of this dedicated IP", "example": "example.com" }, "custom_dns": { "type": "object", "description": "information about the ip's custom dns, if it has been configured", "properties": { "enabled": { "type": "boolean", "description": "a boolean indicating whether custom dns has been configured for this ip", "example": true }, "valid": { "type": "boolean", "description": "whether the ip's custom dns is currently valid", "example": false }, "error": { "type": "string", "description": "if the ip's custom dns is invalid, this will include details about the error", "example": "No A record found" } } }, "warmup": { "type": "object", "description": "information about the ip's warmup status", "properties": { "warming_up": { "type": "boolean", "description": "whether the ip is currently in warmup mode", "example": false }, "start_at": { "type": "string", "format": "date-time", "description": "the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-25 12:00:00" }, "end_at": { "type": "string", "format": "date-time", "description": "the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-30 12:00:00" } } } } } } }, "deprecated": false } }, "/mctemplates/info": { "post": { "x-custom-config": { "methodNameCamel": "mcTemplatesInfo", "methodNameSnake": "mc_templates_info" }, "summary": "Get Mailchimp Template info", "description": "Get information about a Mailchimp Transactional template in your account.", "operationId": "postMcTemplatesInfo", "tags": [ "mctemplates" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "mc_template_id" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "mc_template_id": { "type": "integer", "description": "the id of the Mailchimp template" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "Information about the Mailchimp Transactional template", "properties": { "mc_template_id": { "description": "Mailchimp template ID", "type": "integer", "example": 12345 }, "mc_template_name": { "description": "Template name", "type": "string", "example": "Welcome Email" }, "labels": { "description": "Array of labels (always empty for transactional templates)", "type": "array", "items": { "type": "string" }, "example": [] }, "code": { "description": "Template HTML (draft version)", "type": "string", "example": "
Welcome!
" }, "subject": { "description": "Default subject line", "type": "string", "example": "Welcome to our service" }, "from_email": { "description": "Default sending address", "type": "string", "example": "support@example.com" }, "from_name": { "description": "Default from name", "type": "string", "example": "Support Team" }, "text": { "description": "Template text (draft version)", "type": "string", "example": "Welcome to our service!" }, "publish_code": { "description": "Template HTML (published version)", "type": "string", "example": "
Welcome!
" }, "publish_text": { "description": "Template text (published version)", "type": "string", "example": "Welcome to our service!" }, "published_at": { "description": "Date and time when template was published in UTC YYYY-MM-DD HH:MM:SS format", "type": "string", "format": "date-time", "example": "2025-08-29 18:47:40" }, "created_at": { "description": "Date and time when template was created in UTC YYYY-MM-DD HH:MM:SS format", "type": "string", "format": "date-time", "example": "2025-08-29 18:47:40.26276" }, "updated_at": { "description": "Date and time when template was last updated in UTC YYYY-MM-DD HH:MM:SS format", "type": "string", "format": "date-time", "example": "2025-08-29 18:47:40.26277" }, "draft_updated_at": { "description": "Date and time when template draft was last updated in UTC YYYY-MM-DD HH:MM:SS format", "type": "string", "format": "date-time", "example": "2025-08-29 18:47:40" }, "is_broken_template": { "description": "Whether template has rendering errors", "type": "boolean", "example": false } } } } }, "deprecated": false } }, "/mctemplates/list": { "post": { "x-custom-config": { "methodNameCamel": "mcTemplatesList", "methodNameSnake": "mc_templates_list" }, "summary": "List Mailchimp Transactional Templates", "description": "Return a list of all Mailchimp Transactional templates available to this user.", "operationId": "postMcTemplatesList", "tags": [ "mctemplates" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "search_query": { "description": "Optional search query to filter templates", "type": [ "string", "null" ], "example": "\"\"" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "Array of Mailchimp Transactional templates", "items": { "type": "object", "description": "Information about the Mailchimp Transactional template", "properties": { "mc_template_id": { "description": "Mailchimp template ID", "type": "integer", "example": 12345 }, "mc_template_name": { "description": "Template name", "type": "string", "example": "Welcome Email" }, "labels": { "description": "Array of labels (always empty for transactional templates)", "type": "array", "items": { "type": "string" }, "example": [] }, "code": { "description": "Template HTML (draft version)", "type": "string", "example": "
Welcome!
" }, "subject": { "description": "Default subject line", "type": "string", "example": "Welcome to our service" }, "from_email": { "description": "Default sending address", "type": "string", "example": "support@example.com" }, "from_name": { "description": "Default from name", "type": "string", "example": "Support Team" }, "text": { "description": "Template text (draft version)", "type": "string", "example": "Welcome to our service!" }, "publish_code": { "description": "Template HTML (published version)", "type": "string", "example": "
Welcome!
" }, "publish_text": { "description": "Template text (published version)", "type": "string", "example": "Welcome to our service!" }, "published_at": { "description": "Date and time when template was published in UTC YYYY-MM-DD HH:MM:SS format", "type": "string", "format": "date-time", "example": "2025-08-29 18:47:40" }, "created_at": { "description": "Date and time when template was created in UTC YYYY-MM-DD HH:MM:SS format", "type": "string", "format": "date-time", "example": "2025-08-29 18:47:40.26276" }, "updated_at": { "description": "Date and time when template was last updated in UTC YYYY-MM-DD HH:MM:SS format", "type": "string", "format": "date-time", "example": "2025-08-29 18:47:40.26277" }, "draft_updated_at": { "description": "Date and time when template draft was last updated in UTC YYYY-MM-DD HH:MM:SS format", "type": "string", "format": "date-time", "example": "2025-08-29 18:47:40" }, "is_broken_template": { "description": "Whether template has rendering errors", "type": "boolean", "example": false } } } } } }, "deprecated": false } }, "/mctemplates/render": { "post": { "x-custom-config": { "methodNameCamel": "mcTemplatesRender", "methodNameSnake": "mc_templates_render" }, "summary": "Render Mailchimp Transactional Template", "description": "Render a Mailchimp Transactional template with optional merge variables.", "operationId": "postMcTemplatesRender", "tags": [ "mctemplates" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "mc_template_id" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "mc_template_id": { "type": "integer", "description": "the id of the Mailchimp template to render" }, "mc_template_version": { "description": "Template version - \"published\" or \"draft\". Note: requesting \"published\" when the template has not been published will return a 404 error.", "type": "string", "default": "published", "enum": [ "published", "draft" ], "example": "published" }, "merge_vars": { "type": "array", "description": "an array of merge variables to inject into the template", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "the merge variable name" }, "content": { "type": "string", "description": "the merge variable value" } } } } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "The rendered HTML template", "properties": { "html": { "description": "The rendered HTML content with merge variables applied", "type": "string", "example": "Welcome John!" } } } } }, "deprecated": false } }, "/mctemplates/time-series": { "post": { "x-custom-config": { "methodNameCamel": "mcTemplatesTimeSeries", "methodNameSnake": "mc_templates_time_series" }, "summary": "Get Mailchimp Transactional Template Time Series", "description": "Return the recent history (hourly stats for the last 30 days) for a Mailchimp Transactional template. Returns an empty array if the template exists but has never been used to send messages.", "operationId": "postMcTemplatesTimeSeries", "tags": [ "mctemplates" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "mc_template_id" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "mc_template_id": { "type": "integer", "description": "the id of the Mailchimp template to get time series data for" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "Array of hourly stats for the template", "items": { "type": "object", "properties": { "time": { "description": "The hour as a UTC date string in YYYY-MM-DD HH:00:00 format", "type": "string", "format": "date-time", "example": "2013-01-01 15:00:00" }, "sent": { "description": "The number of emails sent during the time period", "type": "integer", "example": 42 }, "hard_bounces": { "description": "The number of emails hard bounced during the time period", "type": "integer", "example": 42 }, "soft_bounces": { "description": "The number of emails soft bounced during the time period", "type": "integer", "example": 42 }, "rejects": { "description": "The number of emails rejected during the time period", "type": "integer", "example": 42 }, "complaints": { "description": "The number of spam complaints received during the time period", "type": "integer", "example": 42 }, "unsubs": { "description": "The number of unsubscribes during the time period", "type": "integer", "example": 42 }, "opens": { "description": "The number of emails opened during the time period", "type": "integer", "example": 42 }, "unique_opens": { "description": "The number of unique opens during the time period", "type": "integer", "example": 42 }, "clicks": { "description": "The number of URLs clicked during the time period", "type": "integer", "example": 42 }, "unique_clicks": { "description": "The number of unique clicks during the time period", "type": "integer", "example": 42 } } } } } }, "deprecated": false } }, "/messages/send-sms": { "post": { "x-custom-config": { "methodNameCamel": "sendSms", "methodNameSnake": "send_sms" }, "summary": "Send SMS message", "description": "Send a new SMS message through Mandrill", "operationId": "postMessagesSendSms", "tags": [ "messages" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "message" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "message": { "type": "object", "properties": { "sms": { "type": "object", "required": [ "text", "to", "consent", "from" ], "properties": { "text": { "type": "string", "description": "the full SMS content to be sent" }, "to": { "type": "array", "description": "the phone numbers to send the SMS message to", "items": { "type": "string", "description": "a single recipient's phone number", "example": "+10000000000" } }, "from": { "type": "string", "description": "the phone number to send the SMS message from" }, "consent": { "type": "string", "description": "The consent type for the message", "enum": [ "onetime", "recurring", "recurring-no-confirm" ] }, "track_clicks": { "type": "boolean", "description": "whether or not to turn on click tracking for the message" } } } } }, "async": { "type": "boolean", "description": "enable a background sending mode that is optimized for bulk sending. In async mode, messages/send-sms will immediately return a status of \"queued\" for every recipient. To handle rejections when sending in async mode, set up a webhook for the 'reject' event. Defaults to false for messages with no more than 10 recipients; messages with more than 10 recipients are always sent asynchronously, regardless of the value of async." } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "SMS sending results", "items": { "type": "object", "description": "The sending results for a single SMS recipient", "properties": { "to": { "type": "string", "description": "the phone number of the recipient", "example": "+10000000000" }, "from": { "type": "string", "description": "the phone number of the sender", "example": "+10000000000" }, "status": { "type": "string", "description": "the sending status of the message", "enum": [ "sent", "queued", "scheduled", "rejected", "invalid" ], "example": "sent" }, "reject_reason": { "type": "string", "description": "the reason for the rejection if the recipient status is \"rejected\"", "enum": [ "hard-bounce", "soft-bounce", "spam", "unsub", "custom", "invalid-sender", "invalid", "test-mode-limit", "unsigned", "rule" ], "example": "hard-bounce" }, "queue_reason": { "type": "string", "description": "The reason for the queueing if the recipient status is queued", "enum": [ "multiple recipients", "async requested by user" ], "example": "multiple recipients" }, "_id": { "type": "string", "description": "The message's unique id", "example": "abc123abc123abc123abc123abc123" } } } } } } } }, "/messages/send": { "post": { "x-custom-config": { "methodNameCamel": "send", "methodNameSnake": "send" }, "summary": "Send new message", "description": "Send a new transactional message through the Transactional API.", "operationId": "postMessagesSend", "tags": [ "messages" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "message" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "message": { "type": "object", "description": "the information on the message to send", "properties": { "html": { "type": "string", "description": "the full HTML content to be sent" }, "text": { "type": "string", "description": "optional full text content to be sent" }, "subject": { "type": "string", "description": "the message subject" }, "from_email": { "type": "string", "description": "the sender email address", "format": "email" }, "from_name": { "type": "string", "description": "optional from name to be used" }, "to": { "type": "array", "description": "an array of recipient information.", "items": { "type": "object", "description": "a single recipient's information", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "the email address of the recipient", "format": "email" }, "name": { "type": "string", "description": "the optional display name to use for the recipient" }, "type": { "type": "string", "description": "the header type to use for the recipient, defaults to \"to\" if not provided", "enum": [ "to", "cc", "bcc" ] } } } }, "headers": { "type": "object", "description": "optional extra headers to add to the message (most headers are allowed)" }, "important": { "type": "boolean", "description": "whether or not this message is important, and should be delivered ahead of non-important messages" }, "track_opens": { "type": "boolean", "description": "whether or not to turn on open tracking for the message" }, "track_clicks": { "type": "boolean", "description": "whether or not to turn on click tracking for the message" }, "auto_text": { "type": "boolean", "description": "whether or not to automatically generate a text part for messages that are not given text" }, "auto_html": { "type": "boolean", "description": "whether or not to automatically generate an HTML part for messages that are not given HTML" }, "inline_css": { "type": "boolean", "description": "whether or not to automatically inline all CSS styles provided in the message HTML - only for HTML documents less than 256KB in size" }, "url_strip_qs": { "type": "boolean", "description": "whether or not to strip the query string from URLs when aggregating tracked URL data" }, "preserve_recipients": { "type": "boolean", "description": "whether or not to expose all recipients in to \"To\" header for each email" }, "view_content_link": { "type": "boolean", "description": "set to false to remove content logging for sensitive emails" }, "bcc_address": { "type": "string", "description": "an optional address to receive an exact copy of each recipient's email", "format": "email" }, "tracking_domain": { "type": "string", "description": "a custom domain to use for tracking opens and clicks instead of mandrillapp.com" }, "signing_domain": { "type": "string", "description": "a custom domain to use for SPF/DKIM signing instead of mandrill (for \"via\" or \"on behalf of\" in email clients)" }, "return_path_domain": { "type": "string", "description": "a custom domain to use for the messages's return-path" }, "merge": { "type": "boolean", "description": "whether to evaluate merge tags in the message. Will automatically be set to true if either merge_vars or global_merge_vars are provided." }, "merge_language": { "type": "string", "description": "the merge tag language to use when evaluating merge tags, either mailchimp or handlebars", "enum": [ "mailchimp", "handlebars" ] }, "global_merge_vars": { "type": "array", "description": "global merge variables to use for all recipients. You can override these per recipient.", "items": { "type": "object", "description": "a single global merge variable", "properties": { "name": { "type": "string", "description": "the global merge variable's name. Merge variable names are case-insensitive and may not start with _" }, "content": { "type": "string", "description": "the global merge variable's content" } } } }, "merge_vars": { "type": "array", "description": "per-recipient merge variables, which override global merge variables with the same name.", "items": { "type": "object", "description": "per-recipient merge variables", "required": [ "rcpt" ], "properties": { "rcpt": { "type": "string", "description": "the email address of the recipient that the merge variables should apply to", "format": "email" }, "vars": { "type": "array", "description": "the recipient's merge variables", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "the merge variable's name. Merge variable names are case-insensitive and may not start with _" }, "content": { "type": "string", "description": "the merge variable's content" } } } } } } }, "tags": { "type": "array", "description": "an array of string to tag the message with. Stats are accumulated using tags, though we only store the first 100 we see, so this should not be unique or change frequently. Tags should be 50 characters or less. Any tags starting with an underscore are reserved for internal use and will cause errors.", "items": { "type": "string", "description": "a single tag - must not start with an underscore" } }, "subaccount": { "type": "string", "description": "the unique id of a subaccount for this message - must already exist or will fail with an error" }, "google_analytics_domains": { "type": "array", "description": "an array of strings indicating for which any matching URLs will automatically have Google Analytics parameters appended to their query string automatically.", "items": { "type": "string" } }, "google_analytics_campaign": { "type": "string", "description": "optional string indicating the value to set for the utm_campaign tracking parameter. If this isn't provided the email's from address will be used instead.", "format": "email" }, "metadata": { "type": "object", "description": "metadata an associative array of user metadata. Mandrill will store this metadata and make it available for retrieval. In addition, you can select up to 10 metadata fields to index and make searchable using the Mandrill search api.", "properties": { "website": { "type": "string", "description": "a valid website url" } } }, "recipient_metadata": { "type": "array", "description": "Per-recipient metadata that will override the global values specified in the metadata parameter.", "items": { "type": "object", "description": "metadata for a single recipient", "properties": { "rcpt": { "type": "string", "description": "the email address of the recipient that the metadata is associated with", "format": "email" }, "values": { "type": "object", "description": "an associated array containing the recipient's unique metadata. If a key exists in both the per-recipient metadata and the global metadata, the per-recipient metadata will be used.", "properties": { "user_id": { "type": "integer", "description": "" } } } } } }, "attachments": { "type": "array", "description": "an array of supported attachments to add to the message", "items": { "type": "object", "description": "a single supported attachment", "properties": { "type": { "type": "string", "description": "the MIME type of the attachment" }, "name": { "type": "string", "description": "the file name of the attachment" }, "content": { "type": "string", "description": "the content of the attachment as a base64-encoded string" } } } }, "images": { "type": "array", "description": "an array of embedded images to add to the message", "items": { "type": "object", "description": "a single embedded image", "properties": { "type": { "type": "string", "description": "the MIME type of the image - must start with \"image/\"" }, "name": { "type": "string", "description": "the Content ID of the image - use to reference the image in your HTML content" }, "content": { "type": "string", "description": "the content of the image as a base64-encoded string" } } } } } }, "async": { "type": "boolean", "description": "enable a background sending mode that is optimized for bulk sending. In async mode, messages/send will immediately return a status of \"queued\" for every recipient. To handle rejections when sending in async mode, set up a webhook for the 'reject' event. Defaults to false for messages with no more than 10 recipients; messages with more than 10 recipients are always sent asynchronously, regardless of the value of async." }, "ip_pool": { "type": "string", "description": "the name of the dedicated ip pool that should be used to send the message. If you do not have any dedicated IPs, this parameter has no effect. If you specify a pool that does not exist, your default pool will be used instead." }, "send_at": { "type": "string", "description": "when this message should be sent as a UTC timestamp in YYYY-MM-DD HH:MM:SS format. If you specify a time in the past, the message will be sent immediately; for future dates, you're limited to one year from the date of scheduling.", "format": "date-time" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "an array of objects for each recipient containing the key \"email\" with the email address, and details of the message status for that recipient", "items": { "type": "object", "description": "the sending results for a single recipient", "properties": { "email": { "type": "string", "format": "email", "description": "the email address of the recipient", "example": "user@example.com" }, "status": { "type": "string", "description": "the sending status of the recipient", "enum": [ "sent", "queued", "scheduled", "rejected", "invalid" ], "example": "sent" }, "reject_reason": { "type": "string", "description": "the reason for the rejection if the recipient status is \"rejected\"", "enum": [ "hard-bounce", "soft-bounce", "spam", "unsub", "custom", "invalid-sender", "invalid", "test-mode-limit", "unsigned", "rule" ], "example": "hard-bounce" }, "queued_reason": { "type": "string", "description": "the reason for the email being queued if the response status is \"queued\"", "enum": [ "attachments", "multiple-recipients", "free-trial-sends-exhausted", "hourly-quota-exhausted", "monthly-limit-reached", "sending-paused", "sending-suspended", "account-suspended", "sending-backlogged" ], "example": "hourly-quota-exhausted" }, "_id": { "type": "string", "description": "the message's unique id", "example": "a92c74e4c5d74998ba690cd535483bb7" } } } } } }, "deprecated": false } }, "/messages/send-template": { "post": { "x-custom-config": { "methodNameCamel": "sendTemplate", "methodNameSnake": "send_template" }, "summary": "Send using message template", "description": "Send a new transactional message through the Transactional API using a template.", "operationId": "postMessagesSendTemplate", "tags": [ "messages" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "template_name", "template_content", "message" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "template_name": { "type": "string", "description": "the immutable slug of a template that exists in the user's account. Make sure you don't use the template name as this one might change." }, "template_content": { "type": "array", "description": "an array of template content to send. Each item in the array should be a struct with two keys - name: the name of the content block to set the content for, and content: the actual content to put into the block", "items": { "type": "object", "description": "the injection of a single piece of content into a single editable region", "properties": { "name": { "type": "string", "description": "the name of the mc:edit editable region to inject into" }, "content": { "type": "string", "description": "the content to inject" } } } }, "message": { "type": "object", "description": "the other information on the message to send - same as /messages/send, but without the html content", "properties": { "html": { "type": "string", "description": "optional full HTML content to be sent if not in template" }, "text": { "type": "string", "description": "optional full text content to be sent" }, "subject": { "type": "string", "description": "the message subject" }, "from_email": { "type": "string", "description": "the sender email address", "format": "email" }, "from_name": { "type": "string", "description": "optional from name to be used" }, "to": { "type": "array", "description": "an array of recipient information.", "items": { "type": "object", "description": "a single recipient's information", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "the email address of the recipient", "format": "email" }, "name": { "type": "string", "description": "the optional display name to use for the recipient" }, "type": { "type": "string", "description": "the header type to use for the recipient, defaults to \"to\" if not provided", "enum": [ "to", "cc", "bcc" ] } } } }, "headers": { "type": "object", "description": "optional extra headers to add to the message (most headers are allowed)" }, "important": { "type": "boolean", "description": "whether or not this message is important, and should be delivered ahead of non-important messages" }, "track_opens": { "type": "boolean", "description": "whether or not to turn on open tracking for the message" }, "track_clicks": { "type": "boolean", "description": "whether or not to turn on click tracking for the message" }, "auto_text": { "type": "boolean", "description": "whether or not to automatically generate a text part for messages that are not given text" }, "auto_html": { "type": "boolean", "description": "whether or not to automatically generate an HTML part for messages that are not given HTML" }, "inline_css": { "type": "boolean", "description": "whether or not to automatically inline all CSS styles provided in the message HTML - only for HTML documents less than 256KB in size" }, "url_strip_qs": { "type": "boolean", "description": "whether or not to strip the query string from URLs when aggregating tracked URL data" }, "preserve_recipients": { "type": "boolean", "description": "whether or not to expose all recipients in to \"To\" header for each email" }, "view_content_link": { "type": "boolean", "description": "set to false to remove content logging for sensitive emails" }, "bcc_address": { "type": "string", "description": "an optional address to receive an exact copy of each recipient's email", "format": "email" }, "tracking_domain": { "type": "string", "description": "a custom domain to use for tracking opens and clicks instead of mandrillapp.com" }, "signing_domain": { "type": "string", "description": "a custom domain to use for SPF/DKIM signing instead of mandrill (for \"via\" or \"on behalf of\" in email clients)" }, "return_path_domain": { "type": "string", "description": "a custom domain to use for the messages's return-path" }, "merge": { "type": "boolean", "description": "whether to evaluate merge tags in the message. Will automatically be set to true if either merge_vars or global_merge_vars are provided." }, "merge_language": { "type": "string", "description": "the merge tag language to use when evaluating merge tags, either mailchimp or handlebars", "enum": [ "mailchimp", "handlebars" ] }, "global_merge_vars": { "type": "array", "description": "global merge variables to use for all recipients. You can override these per recipient.", "items": { "type": "object", "description": "a single global merge variable", "properties": { "name": { "type": "string", "description": "the global merge variable's name. Merge variable names are case-insensitive and may not start with _" }, "content": { "type": "string", "description": "the global merge variable's content" } } } }, "merge_vars": { "type": "array", "description": "per-recipient merge variables, which override global merge variables with the same name.", "items": { "type": "object", "description": "per-recipient merge variables", "required": [ "rcpt" ], "properties": { "rcpt": { "type": "string", "description": "the email address of the recipient that the merge variables should apply to", "format": "email" }, "vars": { "type": "array", "description": "the recipient's merge variables", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "the merge variable's name. Merge variable names are case-insensitive and may not start with _" }, "content": { "type": "string", "description": "the merge variable's content" } } } } } } }, "tags": { "type": "array", "description": "an array of string to tag the message with. Stats are accumulated using tags, though we only store the first 100 we see, so this should not be unique or change frequently. Tags should be 50 characters or less. Any tags starting with an underscore are reserved for internal use and will cause errors.", "items": { "type": "string", "description": "a single tag - must not start with an underscore" } }, "subaccount": { "type": "string", "description": "the unique id of a subaccount for this message - must already exist or will fail with an error" }, "google_analytics_domains": { "type": "array", "description": "an array of strings indicating for which any matching URLs will automatically have Google Analytics parameters appended to their query string automatically.", "items": { "type": "string" } }, "google_analytics_campaign": { "type": "string", "description": "optional string indicating the value to set for the utm_campaign tracking parameter. If this isn't provided the email's from address will be used instead.", "format": "email" }, "metadata": { "type": "object", "description": "metadata an associative array of user metadata. Mandrill will store this metadata and make it available for retrieval. In addition, you can select up to 10 metadata fields to index and make searchable using the Mandrill search api.", "properties": { "website": { "type": "string", "description": "a valid website url" } } }, "recipient_metadata": { "type": "array", "description": "Per-recipient metadata that will override the global values specified in the metadata parameter.", "items": { "type": "object", "description": "metadata for a single recipient", "properties": { "rcpt": { "type": "string", "description": "the email address of the recipient that the metadata is associated with", "format": "email" }, "values": { "type": "object", "description": "an associated array containing the recipient's unique metadata. If a key exists in both the per-recipient metadata and the global metadata, the per-recipient metadata will be used.", "properties": { "user_id": { "type": "integer", "description": "" } } } } } }, "attachments": { "type": "array", "description": "an array of supported attachments to add to the message", "items": { "type": "object", "description": "a single supported attachment", "properties": { "type": { "type": "string", "description": "the MIME type of the attachment" }, "name": { "type": "string", "description": "the file name of the attachment" }, "content": { "type": "string", "description": "the content of the attachment as a base64-encoded string" } } } }, "images": { "type": "array", "description": "an array of embedded images to add to the message", "items": { "type": "object", "description": "a single embedded image", "properties": { "type": { "type": "string", "description": "the MIME type of the image - must start with \"image/\"" }, "name": { "type": "string", "description": "the Content ID of the image - use to reference the image in your HTML content" }, "content": { "type": "string", "description": "the content of the image as a base64-encoded string" } } } } } }, "async": { "type": "boolean", "description": "enable a background sending mode that is optimized for bulk sending. In async mode, messages/send will immediately return a status of \"queued\" for every recipient. To handle rejections when sending in async mode, set up a webhook for the 'reject' event. Defaults to false for messages with no more than 10 recipients; messages with more than 10 recipients are always sent asynchronously, regardless of the value of async." }, "ip_pool": { "type": "string", "description": "the name of the dedicated ip pool that should be used to send the message. If you do not have any dedicated IPs, this parameter has no effect. If you specify a pool that does not exist, your default pool will be used instead." }, "send_at": { "type": "string", "description": "when this message should be sent as a UTC timestamp in YYYY-MM-DD HH:MM:SS format. If you specify a time in the past, the message will be sent immediately; for future dates, you're limited to one year from the date of scheduling.", "format": "date-time" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "an array of objects for each recipient containing the key \"email\" with the email address, and details of the message status for that recipient", "items": { "type": "object", "description": "the sending results for a single recipient", "properties": { "email": { "type": "string", "format": "email", "description": "the email address of the recipient", "example": "user@example.com" }, "status": { "type": "string", "description": "the sending status of the recipient", "enum": [ "sent", "queued", "rejected", "invalid" ], "example": "sent" }, "reject_reason": { "type": "string", "description": "the reason for the rejection if the recipient status is \"rejected\"", "enum": [ "hard-bounce", "soft-bounce", "spam", "unsub", "custom", "invalid-sender", "invalid", "test-mode-limit", "unsigned", "rule" ], "example": "hard-bounce" }, "queued_reason": { "type": "string", "description": "the reason for the email being queued if the response status is \"queued\"", "enum": [ "attachments", "multiple-recipients", "free-trial-sends-exhausted", "hourly-quota-exhausted", "monthly-limit-reached", "sending-paused", "sending-suspended", "account-suspended", "sending-backlogged" ], "example": "attachments" }, "_id": { "type": "string", "description": "the message's unique id", "example": "a92c74e4c5d74998ba690cd535483bb7" } } } } } }, "deprecated": false } }, "/messages/send-mc-template": { "post": { "x-custom-config": { "methodNameCamel": "sendMcTemplate", "methodNameSnake": "send_mc_template" }, "summary": "Send using Mailchimp template", "description": "Send a new transactional message through Mandrill using a Mailchimp Transactional template.", "operationId": "postMessagesSendMcTemplate", "tags": [ "messages" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "mc_template_id", "message" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "mc_template_id": { "type": "integer", "description": "the id of the Mailchimp template to send" }, "mc_template_version": { "description": "which version of the template to use - \"draft\" for draft content or \"published\" for published content. Defaults to \"published\". Note: requesting \"published\" when the template has not been published will return a 404 error.", "type": "string", "enum": [ "draft", "published" ], "example": "published" }, "message": { "type": "object", "description": "the other information on the message to send - same as /messages/send", "properties": { "html": { "type": "string", "description": "optional full HTML content to be sent if not in template" }, "text": { "type": "string", "description": "optional full text content to be sent" }, "subject": { "type": "string", "description": "the message subject" }, "from_email": { "type": "string", "description": "the sender email address", "format": "email" }, "from_name": { "type": "string", "description": "optional from name to be used" }, "to": { "type": "array", "description": "an array of recipient information.", "items": { "type": "object", "description": "a single recipient's information", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "the email address of the recipient", "format": "email" }, "name": { "type": "string", "description": "the optional display name to use for the recipient" }, "type": { "type": "string", "description": "the header type to use for the recipient, defaults to \"to\" if not provided", "enum": [ "to", "cc", "bcc" ] } } } }, "headers": { "type": "object", "description": "optional extra headers to add to the message (most headers are allowed)" }, "important": { "type": "boolean", "description": "whether or not this message is important, and should be delivered ahead of non-important messages" }, "track_opens": { "type": "boolean", "description": "whether or not to turn on open tracking for the message" }, "track_clicks": { "type": "boolean", "description": "whether or not to turn on click tracking for the message" }, "auto_text": { "type": "boolean", "description": "whether or not to automatically generate a text part for messages that are not given text" }, "auto_html": { "type": "boolean", "description": "whether or not to automatically generate an HTML part for messages that are not given HTML" }, "inline_css": { "type": "boolean", "description": "whether or not to automatically inline all CSS styles provided in the message HTML - only for HTML documents less than 256KB in size" }, "url_strip_qs": { "type": "boolean", "description": "whether or not to strip the query string from URLs when aggregating tracked URL data" }, "preserve_recipients": { "type": "boolean", "description": "whether or not to expose all recipients in to \"To\" header for each email" }, "view_content_link": { "type": "boolean", "description": "set to false to remove content logging for sensitive emails" }, "bcc_address": { "type": "string", "description": "an optional address to receive an exact copy of each recipient's email", "format": "email" }, "tracking_domain": { "type": "string", "description": "a custom domain to use for tracking opens and clicks instead of mandrillapp.com" }, "signing_domain": { "type": "string", "description": "a custom domain to use for SPF/DKIM signing instead of mandrill (for \"via\" or \"on behalf of\" in email clients)" }, "return_path_domain": { "type": "string", "description": "a custom domain to use for the messages's return-path" }, "merge": { "type": "boolean", "description": "whether to evaluate merge tags in the message. Will automatically be set to true if either merge_vars or global_merge_vars are provided." }, "merge_language": { "type": "string", "description": "the merge tag language to use when evaluating merge tags, either mailchimp or handlebars", "enum": [ "mailchimp", "handlebars" ] }, "global_merge_vars": { "type": "array", "description": "global merge variables to use for all recipients. You can override these per recipient.", "items": { "type": "object", "description": "a single global merge variable", "properties": { "name": { "type": "string", "description": "the global merge variable's name. Merge variable names are case-insensitive and may not start with _" }, "content": { "type": "string", "description": "the global merge variable's content" } } } }, "merge_vars": { "type": "array", "description": "per-recipient merge variables, which override global merge variables with the same name.", "items": { "type": "object", "description": "per-recipient merge variables", "required": [ "rcpt" ], "properties": { "rcpt": { "type": "string", "description": "the email address of the recipient that the merge variables should apply to", "format": "email" }, "vars": { "type": "array", "description": "the recipient's merge variables", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "the merge variable's name. Merge variable names are case-insensitive and may not start with _" }, "content": { "type": "string", "description": "the merge variable's content" } } } } } } }, "tags": { "type": "array", "description": "an array of string to tag the message with. Stats are accumulated using tags, though we only store the first 100 we see, so this should not be unique or change frequently. Tags should be 50 characters or less. Any tags starting with an underscore are reserved for internal use and will cause errors.", "items": { "type": "string", "description": "a single tag - must not start with an underscore" } }, "subaccount": { "type": "string", "description": "the unique id of a subaccount for this message - must already exist or will fail with an error" }, "google_analytics_domains": { "type": "array", "description": "an array of strings indicating for which any matching URLs will automatically have Google Analytics parameters appended to their query string automatically.", "items": { "type": "string" } }, "google_analytics_campaign": { "type": "string", "description": "optional string indicating the value to set for the utm_campaign tracking parameter. If this isn't provided the email's from address will be used instead.", "format": "email" }, "metadata": { "type": "object", "description": "metadata an associative array of user metadata. Mandrill will store this metadata and make it available for retrieval. In addition, you can select up to 10 metadata fields to index and make searchable using the Mandrill search api.", "properties": { "website": { "type": "string", "description": "a valid website url" } } }, "recipient_metadata": { "type": "array", "description": "Per-recipient metadata that will override the global values specified in the metadata parameter.", "items": { "type": "object", "description": "metadata for a single recipient", "properties": { "rcpt": { "type": "string", "description": "the email address of the recipient that the metadata is associated with", "format": "email" }, "values": { "type": "object", "description": "an associated array containing the recipient's unique metadata. If a key exists in both the per-recipient metadata and the global metadata, the per-recipient metadata will be used.", "properties": { "user_id": { "type": "integer", "description": "" } } } } } }, "attachments": { "type": "array", "description": "an array of supported attachments to add to the message", "items": { "type": "object", "description": "a single supported attachment", "properties": { "type": { "type": "string", "description": "the MIME type of the attachment" }, "name": { "type": "string", "description": "the file name of the attachment" }, "content": { "type": "string", "description": "the content of the attachment as a base64-encoded string" } } } }, "images": { "type": "array", "description": "an array of embedded images to add to the message", "items": { "type": "object", "description": "a single embedded image", "properties": { "type": { "type": "string", "description": "the MIME type of the image - must start with \"image/\"" }, "name": { "type": "string", "description": "the Content ID of the image - use to reference the image in your HTML content" }, "content": { "type": "string", "description": "the content of the image as a base64-encoded string" } } } } } }, "async": { "type": "boolean", "description": "enable a background sending mode that is optimized for bulk sending. In async mode, messages/send will immediately return a status of \"queued\" for every recipient. To handle rejections when sending in async mode, set up a webhook for the 'reject' event. Defaults to false for messages with no more than 10 recipients; messages with more than 10 recipients are always sent asynchronously, regardless of the value of async." }, "ip_pool": { "type": "string", "description": "the name of the dedicated ip pool that should be used to send the message. If you do not have any dedicated IPs, this parameter has no effect. If you specify a pool that does not exist, your default pool will be used instead." }, "send_at": { "type": "string", "description": "when this message should be sent as a UTC timestamp in YYYY-MM-DD HH:MM:SS format. If you specify a time in the past, the message will be sent immediately; for future dates, you're limited to one year from the date of scheduling.", "format": "date-time" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "an array of objects for each recipient containing the key \"email\" with the email address, and details of the message status for that recipient", "items": { "type": "object", "description": "the sending results for a single recipient", "properties": { "email": { "type": "string", "format": "email", "description": "the email address of the recipient", "example": "user@example.com" }, "status": { "type": "string", "description": "the sending status of the recipient", "enum": [ "sent", "queued", "rejected", "invalid" ], "example": "sent" }, "reject_reason": { "type": "string", "description": "the reason for the rejection if the recipient status is \"rejected\"", "enum": [ "hard-bounce", "soft-bounce", "spam", "unsub", "custom", "invalid-sender", "invalid", "test-mode-limit", "unsigned", "rule" ], "example": "hard-bounce" }, "queued_reason": { "type": "string", "description": "the reason for the email being queued if the response status is \"queued\"", "enum": [ "attachments", "multiple-recipients", "free-trial-sends-exhausted", "hourly-quota-exhausted", "monthly-limit-reached", "sending-paused", "sending-suspended", "account-suspended", "sending-backlogged" ], "example": "attachments" }, "_id": { "type": "string", "description": "the message's unique id", "example": "a92c74e4c5d74998ba690cd535483bb7" } } } } } }, "deprecated": false } }, "/messages/search": { "post": { "x-custom-config": { "methodNameCamel": "search", "methodNameSnake": "search" }, "summary": "Search messages by date", "description": "Search recently sent messages and optionally narrow by date range, tags, senders, and API keys. If no date range is specified, results within the last 7 days are returned. This method may be called up to 20 times per minute. If you need the data more often, you can use /messages/info.json to get the information for a single message, or webhooks to push activity to your own application for querying.", "operationId": "postMessagesSearch", "tags": [ "messages" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "query": { "type": "string", "description": "search terms to find matching messages" }, "date_from": { "type": "string", "description": "start date", "format": "date-time" }, "date_to": { "type": "string", "description": "end date", "format": "date-time" }, "tags": { "type": "array", "description": "an array of tag names to narrow the search to, will return messages that contain ANY of the tags", "items": { "type": "string" } }, "senders": { "type": "array", "description": "an array of sender addresses to narrow the search to, will return messages sent by ANY of the senders", "items": { "type": "string", "description": "a single sender email address", "format": "email" } }, "api_keys": { "type": "array", "description": "an array of API keys to narrow the search to, will return messages sent by ANY of the keys", "items": { "type": "string", "description": "a single API key" } }, "limit": { "type": "integer", "description": "the maximum number of results to return, defaults to 100, 1000 is the maximum", "minimum": 100, "maximum": 1000 } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "an array of objects for each matching message", "items": { "type": "object", "description": "the information for a single matching message", "properties": { "ts": { "type": "integer", "description": "the Unix timestamp from when this message was sent", "example": 1756493251 }, "_id": { "type": "string", "description": "the message's unique id", "example": "a92c74e4c5d74998ba690cd535483bb7" }, "sender": { "type": "string", "format": "email", "description": "the email address of the sender", "example": "from_address@example.com" }, "template": { "type": "string", "description": "the unique name of the template used, if any", "example": "my_template" }, "subject": { "type": "string", "description": "the message's subject line", "example": "This is an example subject" }, "email": { "type": "string", "format": "email", "description": "the recipient email address", "example": "to_address@example.com" }, "tags": { "type": "array", "description": "list of tags on this message", "items": { "type": "string", "description": "individual tag on this message", "example": "my_tag" } }, "opens": { "type": "integer", "description": "how many times has this message been opened", "example": 4 }, "opens_detail": { "type": "array", "description": "list of individual opens for the message", "items": { "type": "object", "description": "information on an individual open", "properties": { "ts": { "type": "integer", "description": "the unix timestamp from when the message was opened", "example": 1756494251 }, "ip": { "type": "string", "description": "the IP address that generated the open", "example": "123.123.123.123" }, "location": { "type": "string", "description": "the approximate region and country that the opening IP is located", "example": "San Francisco, CA, USA" }, "ua": { "type": "string", "description": "the email client or browser data of the open", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3" } } } }, "clicks": { "type": "integer", "description": "how many times has a link been clicked in this message", "example": 2 }, "clicks_detail": { "type": "array", "description": "list of individual clicks for the message", "items": { "type": "object", "description": "information on an individual click", "properties": { "ts": { "type": "integer", "description": "the unix timestamp from when the message was clicked", "example": 1756495251 }, "url": { "type": "string", "description": "the URL that was clicked on", "example": "http://example.com/some/path?with=params" }, "ip": { "type": "string", "description": "the IP address that generated the click", "example": "123.123.123.123" }, "location": { "type": "string", "description": "the approximate region and country that the clicking IP is located", "example": "San Francisco, CA, USA" }, "ua": { "type": "string", "description": "the email client or browser data of the click", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3" } } } }, "state": { "type": "string", "description": "sending status of this message", "enum": [ "sent", "bounced", "rejected" ], "example": "sent" }, "metadata": { "type": "object", "description": "any custom metadata provided when the message was sent", "example": { "website": "www.example.com" } } } } } } }, "deprecated": false } }, "/messages/search-time-series": { "post": { "x-custom-config": { "methodNameCamel": "searchTimeSeries", "methodNameSnake": "search_time_series" }, "summary": "Search messages by hour", "description": "Search the content of recently sent messages and return the aggregated hourly stats for matching messages.", "operationId": "postMessagesSearchTimeSeries", "tags": [ "messages" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "query": { "type": "string", "description": "the search terms to find matching messages for" }, "date_from": { "type": "string", "description": "start date", "format": "date-time" }, "date_to": { "type": "string", "description": "end date", "format": "date-time" }, "tags": { "type": "array", "description": "an array of tag names to narrow the search to, will return messages that contain ANY of the tags", "items": { "type": "string", "description": "a single tag name" } }, "senders": { "type": "array", "description": "an array of sender addresses to narrow the search to, will return messages sent by ANY of the senders", "items": { "type": "string", "description": "a single sender email address" } } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "the array of history information", "items": { "type": "object", "description": "the stats for a single hour", "properties": { "time": { "type": "string", "format": "date-time", "description": "the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 13:00:00" }, "sent": { "type": "integer", "description": "the number of emails that were sent during the hour", "example": 100 }, "hard_bounces": { "type": "integer", "description": "the number of emails that hard bounced during the hour", "example": 5 }, "soft_bounces": { "type": "integer", "description": "the number of emails that soft bounced during the hour", "example": 2 }, "rejects": { "type": "integer", "description": "the number of emails that were rejected during the hour", "example": 1 }, "complaints": { "type": "integer", "description": "the number of spam complaints received during the hour", "example": 0 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes received during the hour", "example": 0 }, "opens": { "type": "integer", "description": "the number of emails opened during the hour", "example": 50 }, "unique_opens": { "type": "integer", "description": "the number of unique opens generated by messages sent during the hour", "example": 40 }, "clicks": { "type": "integer", "description": "the number of tracked URLs clicked during the hour", "example": 30 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks generated by messages sent during the hour", "example": 25 } } } } } }, "deprecated": false } }, "/messages/info": { "post": { "x-custom-config": { "methodNameCamel": "info", "methodNameSnake": "info" }, "summary": "Get message info", "description": "Get the information for a single recently sent message.", "operationId": "postMessagesInfo", "tags": [ "messages" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "id" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "id": { "type": "string", "description": "the unique id of the message to get - passed as the \"_id\" field in webhooks, send calls, or search calls" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the information for the message", "properties": { "ts": { "type": "integer", "description": "the Unix timestamp from when this message was sent", "example": 1756493248 }, "_id": { "type": "string", "description": "the message's unique id", "example": "a92c74e4c5d74998ba690cd535483bb7" }, "sender": { "type": "string", "format": "email", "description": "the email address of the sender", "example": "sender@example.com" }, "template": { "type": "string", "description": "the unique name of the template used, if any", "example": "my_template" }, "subject": { "type": "string", "description": "the message's subject line", "example": "Hello World" }, "email": { "type": "string", "format": "email", "description": "the recipient email address", "example": "recipient@example.com" }, "tags": { "type": "array", "description": "list of tags on this message", "items": { "type": "string", "description": "individual tag on this message", "example": "my_tag" } }, "opens": { "type": "integer", "description": "how many times has this message been opened", "example": 5 }, "opens_detail": { "type": "array", "description": "list of individual opens for the message", "items": { "type": "object", "description": "information on an individual open", "properties": { "ts": { "type": "integer", "description": "the unix timestamp from when the message was opened", "example": 1756494248 }, "ip": { "type": "string", "description": "the IP address that generated the open", "example": "123.123.123.123" }, "location": { "type": "string", "description": "the approximate region and country that the opening IP is located", "example": "San Francisco, CA, USA" }, "ua": { "type": "string", "description": "the email client or browser data of the open", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3" } } } }, "clicks": { "type": "integer", "description": "how many times has a link been clicked in this message" }, "clicks_detail": { "type": "array", "description": "list of individual clicks for the message", "items": { "type": "object", "description": "information on an individual click", "properties": { "ts": { "type": "integer", "description": "the unix timestamp from when the message was clicked", "example": 1756495248 }, "url": { "type": "string", "description": "the URL that was clicked on", "example": "http://example.com/some/path?with=params" }, "ip": { "type": "string", "description": "the IP address that generated the click", "example": "123.123.123.123" }, "location": { "type": "string", "description": "the approximate region and country that the clicking IP is located", "example": "San Francisco, CA, USA" }, "ua": { "type": "string", "description": "the email client or browser data of the click", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3" } } } }, "state": { "type": "string", "description": "sending status of this message", "enum": [ "sent", "bounced", "rejected" ] }, "metadata": { "type": "object", "description": "any custom metadata provided when the message was sent" }, "smtp_events": { "type": "array", "description": "a log of up to 3 smtp events for the message", "items": { "type": "object", "description": "information about a specific smtp event", "properties": { "ts": { "type": "integer", "description": "the Unix timestamp when the event occured", "example": 1756493251 }, "type": { "type": "string", "description": "the message's state as a result of this event", "example": "sent" }, "diag": { "type": "string", "description": "the SMTP response from the recipient's server", "example": "250 2.0.0 OK 1758037166 00724157ae682-72f796974e3si65150137b3.535 - gsmtp" } } } } } } } }, "deprecated": false } }, "/messages/content": { "post": { "x-custom-config": { "methodNameCamel": "content", "methodNameSnake": "content" }, "summary": "Get message content", "description": "Get the full content of a recently sent message.", "operationId": "postMessagesContent", "tags": [ "messages" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "id" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "id": { "type": "string", "description": "the unique id of the message to get - passed as the \"_id\" field in webhooks, send calls, or search calls" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the content of the message", "properties": { "ts": { "type": "integer", "description": "the Unix timestamp from when this message was sent", "example": 1756493248 }, "_id": { "type": "string", "description": "the message's unique id", "example": "a92c74e4c5d74998ba690cd535483bb7" }, "from_email": { "type": "string", "format": "email", "description": "the email address of the sender", "example": "sender@example.com" }, "from_name": { "type": "string", "description": "the alias of the sender (if any)", "example": "Sender Name" }, "subject": { "type": "string", "description": "the message's subject line", "example": "Hello World" }, "to": { "type": "object", "description": "the message recipient's information", "properties": { "email": { "type": "string", "format": "email", "description": "the email address of the recipient", "example": "recipient@example.com" }, "name": { "type": "string", "description": "the alias of the recipient (if any)", "example": "Recipient Name" } } }, "tags": { "type": "array", "description": "list of tags on this message", "items": { "type": "string", "description": "individual tag on this message", "example": "my_tag" } }, "headers": { "type": "object", "description": "the key-value pairs of the custom MIME headers for the message's main document", "example": { "X-Custom-Header": "Custom Value", "X-Another-Header": "Another Value" } }, "text": { "type": "string", "description": "the text part of the message, if any", "example": "This is the text part of the email message." }, "html": { "type": "string", "description": "the HTML part of the message, if any", "example": "

This is the HTML part of the email message.

" }, "attachments": { "type": "array", "description": "an array of any attachments that can be found in the message", "items": { "type": "object", "description": "information about an individual attachment", "properties": { "name": { "type": "string", "description": "the file name of the attachment", "example": "document.pdf" }, "type": { "type": "string", "description": "the MIME type of the attachment", "example": "application/pdf" }, "content": { "type": "string", "description": "the content of the attachment as a base64 encoded string", "example": "JVBERi0xLjQKJcfs..." } } } } } } } }, "deprecated": false } }, "/messages/parse": { "post": { "x-custom-config": { "methodNameCamel": "parse", "methodNameSnake": "parse" }, "summary": "Parse mime document", "description": "Parse the full MIME document for an email message, returning the content of the message broken into its constituent pieces.", "operationId": "postMessagesParse", "tags": [ "messages" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "raw_message" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "raw_message": { "type": "string", "description": "the full MIME document of an email message" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the parsed message", "properties": { "subject": { "type": "string", "description": "the subject of the message", "example": "This is an example subject" }, "from_email": { "type": "string", "format": "email", "description": "the email address of the sender", "example": "sender@example.com" }, "from_name": { "type": "string", "description": "the alias of the sender (if any)", "example": "Sender Name" }, "to": { "type": "array", "description": "an array of any recipients in the message", "items": { "type": "object", "description": "the information on a single recipient", "properties": { "email": { "type": "string", "description": "the email address of the recipient", "example": "recipient@example.com" }, "name": { "type": "string", "description": "the alias of the recipient (if any)", "example": "Recipient Name" } } } }, "headers": { "type": "object", "description": "the key-value pairs of the MIME headers for the message's main document", "example": { "To": "recipient@example.com" } }, "text": { "type": "string", "description": "the text part of the message, if any", "example": "This is the text part of the email message." }, "html": { "type": "string", "description": "the HTML part of the message, if any", "example": "

This is the HTML part of the email message.

" }, "attachments": { "type": "array", "description": "an array of any attachments that can be found in the message", "items": { "type": "object", "description": "information about an individual attachment", "properties": { "name": { "type": "string", "description": "the file name of the attachment", "example": "document.pdf" }, "type": { "type": "string", "description": "the MIME type of the attachment", "example": "application/pdf" }, "binary": { "type": "boolean", "description": "if this is set to true, the attachment is not pure-text, and the content will be base64 encoded", "example": true }, "content": { "type": "string", "description": "the content of the attachment as a base64 encoded string", "example": "JVBERi0xLjQKJcfs..." } } } }, "images": { "type": "array", "description": "an array of any embedded images that can be found in the message", "items": { "type": "object", "description": "information about an individual image", "properties": { "name": { "type": "string", "description": "the Content-ID of the embedded image", "example": "image001.png" }, "type": { "type": "string", "description": "the MIME type of the image", "example": "image/png" }, "content": { "type": "string", "description": "the content of the image as a base64 encoded string", "example": "iVBORw0KGgoAAAANSUhEU..." } } } } } } } }, "deprecated": false } }, "/messages/send-raw": { "post": { "x-custom-config": { "methodNameCamel": "sendRaw", "methodNameSnake": "send_raw" }, "summary": "Send mime document", "description": "Take a raw MIME document for a message, and send it exactly as if it were sent through the Transactional API's SMTP servers.", "operationId": "postMessagesSendRaw", "tags": [ "messages" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "raw_message" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "raw_message": { "type": "string", "description": "the full MIME document of an email message" }, "from_email": { "type": "string", "description": "optionally define the sender address - otherwise we'll use the address found in the provided headers", "format": "email" }, "from_name": { "type": "string", "description": "optionally define the sender alias" }, "to": { "type": "array", "description": "optionally define the recipient to receive the message - otherwise we'll use the To, Cc, and Bcc headers provided in the document", "items": { "type": "string", "description": "the email address of the recipient" } }, "async": { "type": "boolean", "description": "enable a background sending mode that is optimized for bulk sending. In async mode, messages/sendRaw will immediately return a status of \"queued\" for every recipient. To handle rejections when sending in async mode, set up a webhook for the 'reject' event. Defaults to false for messages with no more than 10 recipients; messages with more than 10 recipients are always sent asynchronously, regardless of the value of async." }, "ip_pool": { "type": "string", "description": "the name of the dedicated ip pool that should be used to send the message. If you do not have any dedicated IPs, this parameter has no effect. If you specify a pool that does not exist, your default pool will be used instead." }, "send_at": { "type": "string", "description": "when this message should be sent as a UTC timestamp in YYYY-MM-DD HH:MM:SS format. If you specify a time in the past, the message will be sent immediately; for future dates, you're limited to one year from the date of scheduling.", "format": "date-time" }, "return_path_domain": { "type": "string", "description": "a custom domain to use for the messages's return-path" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "an array of objects for each recipient containing the key \"email\" with the email address, and details of the message status for that recipient", "items": { "type": "object", "description": "the sending results for a single recipient", "properties": { "email": { "type": "string", "format": "email", "description": "the email address of the recipient", "example": "user@example.com" }, "status": { "type": "string", "description": "the sending status of the recipient", "enum": [ "sent", "queued", "scheduled", "rejected", "invalid" ], "example": "sent" }, "reject_reason": { "type": "string", "description": "the reason for the rejection if the recipient status is \"rejected\"", "enum": [ "hard-bounce", "soft-bounce", "spam", "unsub", "custom", "invalid-sender", "invalid", "test-mode-limit", "unsigned", "rule" ], "example": "hard-bounce" }, "queued_reason": { "type": "string", "description": "the reason for the email being queued if the response status is \"queued\"", "enum": [ "attachments", "multiple-recipients", "free-trial-sends-exhausted", "hourly-quota-exhausted", "monthly-limit-reached", "sending-paused", "sending-suspended", "account-suspended", "sending-backlogged" ], "example": "hourly-quota-exhausted" }, "_id": { "type": "string", "description": "the message's unique id", "example": "a92c74e4c5d74998ba690cd535483bb7" } } } } } }, "deprecated": false } }, "/messages/list-scheduled": { "post": { "x-custom-config": { "methodNameCamel": "listScheduled", "methodNameSnake": "list_scheduled" }, "summary": "List scheduled emails", "description": "Queries your scheduled emails.", "operationId": "postMessagesListScheduled", "tags": [ "messages" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "to": { "type": "string", "description": "an optional recipient address to restrict results to", "format": "email" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "a list of up to 1000 scheduled emails", "items": { "type": "object", "description": "a scheduled email", "properties": { "_id": { "type": "string", "description": "the scheduled message id", "example": "5a1b2c3d4e5f678901234567" }, "created_at": { "type": "string", "format": "date-time", "description": "the UTC timestamp when the message was created, in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-15 13:00:00" }, "send_at": { "type": "string", "format": "date-time", "description": "the UTC timestamp when the message will be sent, in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 13:00:00" }, "from_email": { "type": "string", "format": "email", "description": "the email's sender address", "example": "sender@example.com" }, "to": { "type": "string", "format": "email", "description": "the email's recipient", "example": "recipient@example.com" }, "subject": { "type": "string", "description": "the email's subject", "example": "Hello World" } } } } } }, "deprecated": false } }, "/messages/cancel-scheduled": { "post": { "x-custom-config": { "methodNameCamel": "cancelScheduled", "methodNameSnake": "cancel_scheduled" }, "summary": "Cancel scheduled email", "description": "Cancels a scheduled email.", "operationId": "postMessagesCancelScheduled", "tags": [ "messages" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "id" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "id": { "type": "string", "description": "a scheduled email id, as returned by any of the messages/send calls or messages/list-scheduled" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "information about the scheduled email that was cancelled.", "items": { "type": "object", "description": "a scheduled email", "properties": { "_id": { "type": "string", "description": "the scheduled message id", "example": "5a1b2c3d4e5f678901234567" }, "created_at": { "type": "string", "format": "date-time", "description": "the UTC timestamp when the message was created, in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-15 13:00:00" }, "send_at": { "type": "string", "format": "date-time", "description": "the UTC timestamp when the message will be sent, in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 13:00:00" }, "from_email": { "type": "string", "format": "email", "description": "the email's sender address", "example": "sender@example.com" }, "to": { "type": "string", "format": "email", "description": "the email's recipient", "example": "recipient@example.com" }, "subject": { "type": "string", "description": "the email's subject", "example": "Hello World" } } } } } }, "deprecated": false } }, "/messages/reschedule": { "post": { "x-custom-config": { "methodNameCamel": "reschedule", "methodNameSnake": "reschedule" }, "summary": "Reschedule email", "description": "Reschedules a scheduled email.", "operationId": "postMessagesReschedule", "tags": [ "messages" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "id", "send_at" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "id": { "type": "string", "description": "a scheduled email id, as returned by any of the messages/send calls or messages/list-scheduled" }, "send_at": { "type": "string", "description": "the new UTC timestamp when the message should sent. Mandrill can't time travel, so if you specify a time in past the message will be sent immediately; for future dates, you're limited to one year from the date of scheduling.", "format": "date-time" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "information about the scheduled email that was rescheduled.", "items": { "type": "object", "description": "a scheduled email", "properties": { "_id": { "type": "string", "description": "the scheduled message id", "example": "5a1b2c3d4e5f678901234567" }, "created_at": { "type": "string", "format": "date-time", "description": "the UTC timestamp when the message was created, in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-15 13:00:00" }, "send_at": { "type": "string", "format": "date-time", "description": "the UTC timestamp when the message will be sent, in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 13:00:00" }, "from_email": { "type": "string", "format": "email", "description": "the email's sender address", "example": "sender@example.com" }, "to": { "type": "string", "format": "email", "description": "the email's recipient", "example": "recipient@example.com" }, "subject": { "type": "string", "description": "the email's subject", "example": "Hello World" } } } } } }, "deprecated": false } }, "/metadata/list": { "post": { "x-custom-config": { "methodNameCamel": "list", "methodNameSnake": "list" }, "summary": "List metadata fields", "description": "Get the list of custom metadata fields indexed for the account.", "operationId": "postMetadataList", "tags": [ "metadata" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "the custom metadata fields for the account", "items": { "type": "object", "description": "the individual custom metadata field info", "properties": { "name": { "type": "string", "description": "the unique identifier of the metadata field to update", "example": "product_id" }, "state": { "type": "string", "description": "the current state of the metadata field", "enum": [ "active", "delete", "index" ], "example": "active" }, "view_template": { "type": "string", "description": "Mustache template to control how the metadata is rendered in your activity log", "example": "Product: *|product_id|*" } } } } } }, "deprecated": false } }, "/metadata/add": { "post": { "x-custom-config": { "methodNameCamel": "add", "methodNameSnake": "add" }, "summary": "Add metadata field", "description": "Add a new custom metadata field to be indexed for the account.", "operationId": "postMetadataAdd", "tags": [ "metadata" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "name" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "name": { "type": "string", "description": "a unique identifier for the metadata field", "maxLength": 64 }, "view_template": { "type": "string", "description": "Mustache template to control how the metadata is rendered in your activity log", "maxLength": 1024 } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the information saved about the new metadata field", "properties": { "name": { "type": "string", "description": "the unique identifier of the metadata field to update", "example": "product_id" }, "state": { "type": "string", "description": "the current state of the metadata field", "enum": [ "active", "delete", "index" ], "example": "active" }, "view_template": { "type": "string", "description": "Mustache template to control how the metadata is rendered in your activity log", "example": "Product: *|product_id|*" } } } } }, "deprecated": false } }, "/metadata/update": { "post": { "x-custom-config": { "methodNameCamel": "update", "methodNameSnake": "update" }, "summary": "Update metadata field", "description": "Update an existing custom metadata field.", "operationId": "postMetadataUpdate", "tags": [ "metadata" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "name", "view_template" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "name": { "type": "string", "description": "the unique identifier of the metadata field to update" }, "view_template": { "type": "string", "description": "Mustache template to control how the metadata is rendered in your activity log", "maxLength": 1024 } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the information for the updated metadata field", "properties": { "name": { "type": "string", "description": "the unique identifier of the metadata field to update", "example": "product_id" }, "state": { "type": "string", "description": "the current state of the metadata field", "enum": [ "active", "delete", "index" ], "example": "active" }, "view_template": { "type": "string", "description": "Mustache template to control how the metadata is rendered in your activity log", "example": "Product: *|product_id|*" } } } } }, "deprecated": false } }, "/metadata/delete": { "post": { "x-custom-config": { "methodNameCamel": "delete", "methodNameSnake": "delete" }, "summary": "Delete metadata field", "description": "Delete an existing custom metadata field. Deletion isn't instataneous, and /metadata/list will continue to return the field until the asynchronous deletion process is complete.", "operationId": "postMetadataDelete", "tags": [ "metadata" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "name" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "name": { "type": "string", "description": "the unique identifier of the metadata field to update" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the information for the deleted metadata field", "properties": { "name": { "type": "string", "description": "the unique identifier of the metadata field to update", "example": "product_id" }, "state": { "type": "string", "description": "the current state of the metadata field", "enum": [ "active", "delete", "index" ], "example": "active" }, "view_template": { "type": "string", "description": "Mustache template to control how the metadata is rendered in your activity log", "example": "Product: *|product_id|*" } } } } }, "deprecated": false } }, "/rejects/add": { "post": { "x-custom-config": { "methodNameCamel": "add", "methodNameSnake": "add" }, "summary": "Add email to denylist", "description": "Adds an email to your email rejection denylist. Addresses that you add manually will never expire and there is no reputation penalty for removing them from your denylist. Attempting to denylist an address that has been added to the allowlist will have no effect.", "operationId": "postRejectsAdd", "tags": [ "rejects" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "email" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "email": { "type": "string", "description": "an email address to block", "format": "email" }, "comment": { "type": "string", "description": "an optional comment describing the rejection" }, "subaccount": { "type": "string", "description": "an optional unique identifier for the subaccount to limit the denylist entry", "maxLength": 255 } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "a status object containing the address and the result of the operation", "properties": { "email": { "type": "string", "format": "email", "description": "the email address you provided", "example": "user@example.com" }, "added": { "type": "boolean", "description": "whether the operation succeeded", "example": true } } } } }, "deprecated": false } }, "/rejects/list": { "post": { "x-custom-config": { "methodNameCamel": "list", "methodNameSnake": "list" }, "summary": "List denylisted emails", "description": "Retrieves your email rejection denylist. You can provide an email address to limit the results. Returns up to 1000 results. By default, entries that have expired are excluded from the results; set include_expired to true to include them.", "operationId": "postRejectsList", "tags": [ "rejects" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "email": { "type": "string", "description": "an optional email address to search by", "format": "email" }, "include_expired": { "type": "boolean", "description": "whether to include rejections that have already expired." }, "subaccount": { "type": "string", "description": "an optional unique identifier for the subaccount to limit the denylist", "maxLength": 255 } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "Up to 1000 rejection entries", "items": { "type": "object", "description": "the information for each rejection entry", "properties": { "email": { "type": "string", "format": "email", "description": "the email that is blocked", "example": "user@example.com" }, "reason": { "type": "string", "description": "the type of event (hard-bounce, soft-bounce, spam, unsub, custom) that caused this rejection", "example": "hard-bounce" }, "detail": { "type": "string", "description": "extended details about the event, such as the SMTP diagnostic for bounces or the comment for manually-created rejections", "example": "550 5.1.1 The email account that you tried to reach does not exist." }, "created_at": { "type": "string", "format": "date-time", "description": "when the email was added to the denylist", "example": "2025-04-29 13:00:00" }, "last_event_at": { "type": "string", "format": "date-time", "description": "the timestamp of the most recent event that either created or renewed this rejection", "example": "2025-04-29 13:00:00" }, "expires_at": { "type": "string", "format": "date-time", "description": "when the denylist entry will expire (this may be in the past)", "example": "2025-05-29 13:00:00" }, "expired": { "type": "boolean", "description": "whether the denylist entry has expired", "example": true }, "sender": { "type": "object", "description": "the sender that this denylist entry applies to, or null if none.", "properties": { "address": { "type": "string", "format": "email", "description": "the sender's email address", "example": "sender@example.com" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the sender was first seen by Mandrill as a UTC date string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-15 13:00:00" }, "sent": { "type": "integer", "description": "the total number of messages sent by this sender", "example": 20 }, "hard_bounces": { "type": "integer", "description": "the total number of hard bounces by messages by this sender", "example": 5 }, "soft_bounces": { "type": "integer", "description": "the total number of soft bounces by messages by this sender", "example": 3 }, "rejects": { "type": "integer", "description": "the total number of rejected messages by this sender", "example": 2 }, "complaints": { "type": "integer", "description": "the total number of spam complaints received for messages by this sender", "example": 1 }, "unsubs": { "type": "integer", "description": "the total number of unsubscribe requests received for messages by this sender", "example": 0 }, "opens": { "type": "integer", "description": "the total number of times messages by this sender have been opened", "example": 10 }, "clicks": { "type": "integer", "description": "the total number of times tracked URLs in messages by this sender have been clicked", "example": 5 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent for this sender", "example": 8 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent for this sender", "example": 4 } } }, "subaccount": { "type": "string", "description": "the subaccount that this denylist entry applies to, or null if none.", "example": "my_subaccount" } } } } } }, "deprecated": false } }, "/rejects/delete": { "post": { "x-custom-config": { "methodNameCamel": "delete", "methodNameSnake": "delete" }, "summary": "Delete email from denylist", "description": "Deletes an email rejection. There is no limit to how many rejections you can remove from your denylist, but keep in mind that each deletion has an affect on your reputation.", "operationId": "postRejectsDelete", "tags": [ "rejects" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "email" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "email": { "type": "string", "description": "an email address", "format": "email" }, "subaccount": { "type": "string", "description": "an optional unique identifier for the subaccount to limit the denylist deletion", "maxLength": 255 } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "a status object containing the address and whether the deletion succeeded.", "properties": { "email": { "type": "string", "format": "email", "description": "the email address that was removed from the denylist", "example": "user@example.com" }, "deleted": { "type": "boolean", "description": "whether the address was deleted successfully.", "example": true }, "subaccount": { "type": "string", "description": "the subaccount denylist that the address was removed from, if any", "example": "my_subaccount" } } } } }, "deprecated": false } }, "/senders/list": { "post": { "x-custom-config": { "methodNameCamel": "list", "methodNameSnake": "list" }, "summary": "List account senders", "description": "Return the senders that have tried to use this account.", "operationId": "postSendersList", "tags": [ "senders" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "an array of sender data, one for each sending addresses used by the account", "items": { "type": "object", "description": "the information on each sending address in the account", "properties": { "address": { "type": "string", "format": "email", "description": "the sender's email address", "example": "user@example.com" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the sender was first seen by Mandrill as a UTC date string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-15 13:00:00.18061" }, "sent": { "type": "integer", "description": "the total number of messages sent by this sender", "example": 20 }, "hard_bounces": { "type": "integer", "description": "the total number of hard bounces by messages by this sender", "example": 5 }, "soft_bounces": { "type": "integer", "description": "the total number of soft bounces by messages by this sender", "example": 2 }, "rejects": { "type": "integer", "description": "the total number of rejected messages by this sender", "example": 1 }, "complaints": { "type": "integer", "description": "the total number of spam complaints received for messages by this sender", "example": 0 }, "unsubs": { "type": "integer", "description": "the total number of unsubscribe requests received for messages by this sender", "example": 0 }, "opens": { "type": "integer", "description": "the total number of times messages by this sender have been opened", "example": 10 }, "clicks": { "type": "integer", "description": "the total number of times tracked URLs in messages by this sender have been clicked", "example": 5 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent for this sender", "example": 8 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent for this sender", "example": 3 } } } } } }, "deprecated": false } }, "/senders/domains": { "post": { "x-custom-config": { "methodNameCamel": "domains", "methodNameSnake": "domains" }, "summary": "List sender domains", "description": "Returns the sender domains that have been added to this account.", "operationId": "postSendersDomains", "tags": [ "senders" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "an array of sender domain data, one for each sending domain used by the account", "items": { "type": "object", "description": "the information on each sending domain for the account", "properties": { "domain": { "type": "string", "description": "the sender domain name", "example": "example.com" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the sending domain was first seen as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-15 13:22:49" }, "last_tested_at": { "type": "string", "format": "date-time", "description": "when the domain's DNS settings were last tested as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 13:00:00" }, "spf": { "type": "object", "description": "details about the domain's SPF record", "properties": { "valid": { "type": "boolean", "description": "whether the domain's SPF record is valid for use with Mandrill", "example": true }, "valid_after": { "type": "string", "format": "date-time", "description": "when the domain's SPF record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.", "example": "2025-04-24 14:00:00" }, "error": { "type": "string", "description": "an error describing the spf record, or null if the record is correct", "example": "This domain has an SPF record, but it doesn't include Mandrill." } } }, "dkim": { "type": "object", "description": "details about the domain's Legacy DKIM record", "properties": { "valid": { "type": "boolean", "description": "whether the domain's Legacy DKIM record is valid for use with Mandrill", "example": false }, "valid_after": { "type": "string", "format": "date-time", "description": "when the domain's Legacy DKIM record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.", "example": "2025-04-15 13:00:00" }, "error": { "type": "string", "description": "an error describing the Legacy DKIM record, or null if the record is correct", "example": "does not match the required CNAME target of dkim1.mandrillapp.com. Please verify that the target was entered exactly as requested and try again." } } }, "dkim2": { "type": "object", "description": "details about the domain's rotatable 2048 bit DKIM record", "properties": { "valid": { "type": "boolean", "description": "whether the domain's DKIM record is valid for use with Mandrill", "example": true }, "valid_after": { "type": "string", "format": "date-time", "description": "when the domain's DKIM record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.", "example": "2025-04-15 13:00:00" }, "error": { "type": "string", "description": "an error describing the DKIM record, or null if the record is correct", "example": "does not match the required CNAME target of dkim2.mandrillapp.com. Please verify that the target was entered exactly as requested and try again." } } }, "dmarc": { "type": "object", "description": "details about the domain's DMARC record", "properties": { "valid": { "type": "boolean", "description": "whether the domain's DMARC record is valid for use with Mandrill", "example": false }, "error": { "type": "string", "description": "an error describing the DMARC record, or null if the record is correct", "example": "The record doesn't begin with a valid version tag." } } }, "verified_at": { "type": "string", "format": "date-time", "description": "if the domain has been verified, this indicates when that verification occurred as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-20 13:00:00" }, "valid_signing": { "type": "boolean", "description": "whether this domain can be used to authenticate mail, either for itself or as a custom signing domain. If this is false but spf and dkim are both valid, you will need to verify the domain before using it to authenticate mail", "example": false }, "verify_txt_key": { "type": "string", "description": "a unique key used to verify a domain by adding a TXT record. Append this key to 'mandrill_verify.' and add it to your domain's TXT records to verify", "example": "wtwm-d3lEsGLX6yeb24weA" } } } } } }, "deprecated": false } }, "/senders/add-domain": { "post": { "x-custom-config": { "methodNameCamel": "addDomain", "methodNameSnake": "add_domain" }, "summary": "Add sender domain", "description": "Adds a sender domain to your account. Sender domains are added automatically as you send, but you can use this call to add them ahead of time.", "operationId": "postSendersAddDomain", "tags": [ "senders" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "domain" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "domain": { "type": "string", "description": "a domain name" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "information about the domain", "properties": { "domain": { "type": "string", "description": "the sender domain name", "example": "example.com" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the sending domain was first seen as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-15 13:22:49" }, "last_tested_at": { "type": "string", "format": "date-time", "description": "when the domain's DNS settings were last tested as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 13:00:00" }, "spf": { "type": "object", "description": "details about the domain's SPF record", "properties": { "valid": { "type": "boolean", "description": "whether the domain's SPF record is valid for use with Mandrill", "example": true }, "valid_after": { "type": "string", "format": "date-time", "description": "when the domain's SPF record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.", "example": "2025-04-24 14:00:00" }, "error": { "type": "string", "description": "an error describing the spf record, or null if the record is correct", "example": "This domain has an SPF record, but it doesn't include Mandrill." } } }, "dkim": { "type": "object", "description": "details about the domain's DKIM record", "properties": { "valid": { "type": "boolean", "description": "whether the domain's DKIM record is valid for use with Mandrill", "example": true }, "valid_after": { "type": "string", "format": "date-time", "description": "when the domain's DKIM record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.", "example": "2025-04-15 13:00:00" }, "error": { "type": "string", "description": "an error describing the DKIM record, or null if the record is correct", "example": "does not match the required CNAME target of dkim.mandrillapp.com. Please verify that the target was entered exactly as requested and try again." } } }, "verified_at": { "type": "string", "format": "date-time", "description": "if the domain has been verified, this indicates when that verification occurred as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-20 13:00:00" }, "valid_signing": { "type": "boolean", "description": "whether this domain can be used to authenticate mail, either for itself or as a custom signing domain. If this is false but spf and dkim are both valid, you will need to verify the domain before using it to authenticate mail", "example": false }, "verify_txt_key": { "type": "string", "description": "a unique key used to verify a domain by adding a TXT record. Append this key to 'mandrill_verify.' and add it to your domain's TXT records to verify", "example": "wtwm-d3lEsGLX6yeb24weA" } } } } }, "deprecated": false } }, "/senders/delete-domain": { "post": { "x-custom-config": { "methodNameCamel": "deleteDomain", "methodNameSnake": "delete_domain" }, "summary": "Delete sender domain", "description": "Deletes an unverified sender domain from your account. Verified domains cannot be deleted via API and require login confirmation.", "operationId": "postSendersDeleteDomain", "tags": [ "senders" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "domain" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "domain": { "type": "string", "description": "the domain name to delete" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "Information about the deleted domain", "properties": { "domain": { "type": "string", "format": "hostname", "example": "example.com" }, "created_at": { "description": "The date and time that the sending domain was first seen.", "type": "string", "format": "date-time" }, "last_tested_at": { "description": "The date and time that the sending domain was last tested.", "type": "string", "format": "date-time" }, "spf": { "description": "Details about the domain's SPF record.", "properties": { "valid": { "description": "Whether this verification is valid.", "type": "boolean" }, "valid_after": { "description": "The date and time that this verification was last tested.", "type": "string", "format": "date-time" }, "error": { "description": "An error message indicating why the verification failed.", "type": "string" } }, "type": "object" }, "dkim": { "description": "Details about the domain's DKIM record.", "properties": { "valid": { "description": "Whether this verification is valid.", "type": "boolean" }, "valid_after": { "description": "The date and time that this verification was last tested.", "type": "string", "format": "date-time" }, "error": { "description": "An error message indicating why the verification failed.", "type": "string" } }, "type": "object" }, "dkim2": { "description": "Details about the domain's second DKIM record.", "properties": { "valid": { "description": "Whether this verification is valid.", "type": "boolean" }, "valid_after": { "description": "The date and time that this verification was last tested.", "type": "string", "format": "date-time" }, "error": { "description": "An error message indicating why the verification failed.", "type": "string" } }, "type": "object" }, "dmarc": { "description": "Details about the domain's DMARC record.", "properties": { "valid": { "description": "Whether this verification is valid.", "type": "boolean" }, "error": { "description": "An error message indicating why the verification failed.", "type": "string" } }, "type": "object" }, "verified_at": { "description": "The date and time that the sending domain was verified.", "type": "string", "format": "date-time" }, "valid_signing": { "description": "Whether this domain can be used to sign messages.", "type": "boolean" }, "verify_txt_key": { "description": "The key for the TXT record used to verify the domain.", "type": "string" } } } } }, "deprecated": false } }, "/senders/check-domain": { "post": { "x-custom-config": { "methodNameCamel": "checkDomain", "methodNameSnake": "check_domain" }, "summary": "Check domain settings", "description": "Checks the SPF and DKIM settings for a domain, as well the domain verification. If you haven't already added this domain to your account, it will be added automatically.", "operationId": "postSendersCheckDomain", "tags": [ "senders" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "domain" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "domain": { "type": "string", "description": "a domain name" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "information about the sender domain", "properties": { "domain": { "type": "string", "description": "the sender domain name", "example": "example.com" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the sending domain was first seen as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-15 13:22:49" }, "last_tested_at": { "type": "string", "format": "date-time", "description": "when the domain's DNS settings were last tested as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 13:00:00" }, "spf": { "type": "object", "description": "details about the domain's SPF record", "properties": { "valid": { "type": "boolean", "description": "whether the domain's SPF record is valid for use with Mandrill", "example": true }, "valid_after": { "type": "string", "format": "date-time", "description": "when the domain's SPF record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.", "example": "2025-04-24 14:00:00" }, "error": { "type": "string", "description": "an error describing the spf record, or null if the record is correct", "example": "This domain has an SPF record, but it doesn't include Mandrill." } } }, "dkim": { "type": "object", "description": "details about the domain's Legacy DKIM record", "properties": { "valid": { "type": "boolean", "description": "whether the domain's Legacy DKIM record is valid for use with Mandrill", "example": true }, "valid_after": { "type": "string", "format": "date-time", "description": "when the domain's Legacy DKIM record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.", "example": "2025-04-15 13:00:00" }, "error": { "type": "string", "description": "an error describing the Legacy DKIM record, or null if the record is correct", "example": "does not match the required CNAME target of dkim1.mandrillapp.com. Please verify that the target was entered exactly as requested and try again." } } }, "dkim2": { "type": "object", "description": "details about the domain's rotatable 2048 bit DKIM record", "properties": { "valid": { "type": "boolean", "description": "whether the domain's DKIM record is valid for use with Mandrill", "example": true }, "valid_after": { "type": "string", "format": "date-time", "description": "when the domain's DKIM record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.", "example": "2025-04-15 13:00:00" }, "error": { "type": "string", "description": "an error describing the DKIM record, or null if the record is correct", "example": "does not match the required CNAME target of dkim2.mandrillapp.com. Please verify that the target was entered exactly as requested and try again." } } }, "dmarc": { "type": "object", "description": "details about the domain's DMARC record", "properties": { "valid": { "type": "boolean", "description": "whether the domain's DMARC record is valid for use with Mandrill", "example": false }, "error": { "type": "string", "description": "an error describing the DMARC record, or null if the record is correct", "example": "The record doesn't begin with a valid version tag." } } }, "verified_at": { "type": "string", "format": "date-time", "description": "if the domain has been verified, this indicates when that verification occurred as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-20 13:00:00" }, "valid_signing": { "type": "boolean", "description": "whether this domain can be used to authenticate mail, either for itself or as a custom signing domain. If this is false but spf and dkim are both valid, you will need to verify the domain before using it to authenticate mail", "example": false }, "verify_txt_key": { "type": "string", "description": "a unique key used to verify a domain by adding a TXT record. Append this key to 'mandrill_verify.' and add it to your domain's TXT records to verify", "example": "wtwm-d3lEsGLX6yeb24weA" } } } } }, "deprecated": false } }, "/senders/verify-domain": { "post": { "x-custom-config": { "methodNameCamel": "verifyDomain", "methodNameSnake": "verify_domain" }, "summary": "Verify domain", "description": "Sends a verification email in order to verify ownership of a domain. Domain verification is a required step to confirm ownership of a domain. Once a domain has been verified in a Transactional API account, other accounts may not have their messages signed by that domain unless they also verify the domain. This prevents other Transactional API accounts from sending mail signed by your domain.", "operationId": "postSendersVerifyDomain", "tags": [ "senders" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "domain", "mailbox" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "domain": { "type": "string", "description": "domain name at which you can receive email" }, "mailbox": { "type": "string", "description": "a mailbox at the domain where the verification email should be sent" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "information about the verification that was sent", "properties": { "status": { "type": "string", "description": "\"sent\" indicates that the verification has been sent, \"already_verified\" indicates that the domain has already been verified with your account", "example": "sent" }, "domain": { "type": "string", "description": "the domain name you provided", "example": "example.com" }, "email": { "type": "string", "format": "email", "description": "the email address the verification email was sent to", "example": "verify@example.com" } } } } }, "deprecated": false } }, "/senders/info": { "post": { "x-custom-config": { "methodNameCamel": "info", "methodNameSnake": "info" }, "summary": "Get sender info", "description": "Return more detailed information about a single sender, including aggregates of recent stats.", "operationId": "postSendersInfo", "tags": [ "senders" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "address" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "address": { "type": "string", "description": "the email address of the sender", "format": "email" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the detailed information on the sender", "properties": { "address": { "type": "string", "format": "email", "description": "the sender's email address", "example": "sender@example.com" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the sender was first seen by Mandrill as a UTC date string in YYYY-MM-DD HH:MM:SS format", "example": "2023-01-01 12:00:00.12512" }, "sent": { "type": "integer", "description": "the total number of messages sent by this sender", "example": 100 }, "hard_bounces": { "type": "integer", "description": "the total number of hard bounces by messages by this sender", "example": 5 }, "soft_bounces": { "type": "integer", "description": "the total number of soft bounces by messages by this sender", "example": 2 }, "rejects": { "type": "integer", "description": "the total number of rejected messages by this sender", "example": 1 }, "complaints": { "type": "integer", "description": "the total number of spam complaints received for messages by this sender", "example": 0 }, "unsubs": { "type": "integer", "description": "the total number of unsubscribe requests received for messages by this sender", "example": 0 }, "opens": { "type": "integer", "description": "the total number of times messages by this sender have been opened", "example": 10 }, "clicks": { "type": "integer", "description": "the total number of times tracked URLs in messages by this sender have been clicked", "example": 5 }, "stats": { "type": "object", "description": "an aggregate summary of the sender's sending stats", "properties": { "today": { "type": "object", "description": "stats for this sender so far today", "properties": { "sent": { "type": "integer", "description": "the number of emails sent for this sender so far today", "example": 10 }, "hard_bounces": { "type": "integer", "description": "the number of emails hard bounced for this sender so far today", "example": 1 }, "soft_bounces": { "type": "integer", "description": "the number of emails soft bounced for this sender so far today", "example": 2 }, "rejects": { "type": "integer", "description": "the number of emails rejected for sending this sender so far today", "example": 1 }, "complaints": { "type": "integer", "description": "the number of spam complaints for this sender so far today", "example": 0 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes for this sender so far today", "example": 0 }, "opens": { "type": "integer", "description": "the number of times emails have been opened for this sender so far today", "example": 10 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent for this sender so far today", "example": 5 }, "clicks": { "type": "integer", "description": "the number of URLs that have been clicked for this sender so far today", "example": 2 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent for this sender so far today", "example": 1 } } }, "last_7_days": { "type": "object", "description": "stats for this sender in the last 7 days", "properties": { "sent": { "type": "integer", "description": "the number of emails sent for this sender in the last 7 days", "example": 70 }, "hard_bounces": { "type": "integer", "description": "the number of emails hard bounced for this sender in the last 7 days", "example": 10 }, "soft_bounces": { "type": "integer", "description": "the number of emails soft bounced for this sender in the last 7 days", "example": 5 }, "rejects": { "type": "integer", "description": "the number of emails rejected for sending this sender in the last 7 days", "example": 3 }, "complaints": { "type": "integer", "description": "the number of spam complaints for this sender in the last 7 days", "example": 1 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes for this sender in the last 7 days", "example": 2 }, "opens": { "type": "integer", "description": "the number of times emails have been opened for this sender in the last 7 days", "example": 30 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent for this sender in the last 7 days", "example": 15 }, "clicks": { "type": "integer", "description": "the number of URLs that have been clicked for this sender in the last 7 days", "example": 5 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent for this sender in the last 7 days", "example": 3 } } }, "last_30_days": { "type": "object", "description": "stats for this sender in the last 30 days", "properties": { "sent": { "type": "integer", "description": "the number of emails sent for this sender in the last 30 days", "example": 300 }, "hard_bounces": { "type": "integer", "description": "the number of emails hard bounced for this sender in the last 30 days", "example": 15 }, "soft_bounces": { "type": "integer", "description": "the number of emails soft bounced for this sender in the last 30 days", "example": 5 }, "rejects": { "type": "integer", "description": "the number of emails rejected for sending this sender in the last 30 days", "example": 2 }, "complaints": { "type": "integer", "description": "the number of spam complaints for this sender in the last 30 days", "example": 1 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes for this sender in the last 30 days", "example": 0 }, "opens": { "type": "integer", "description": "the number of times emails have been opened for this sender in the last 30 days", "example": 100 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent for this sender in the last 30 days", "example": 75 }, "clicks": { "type": "integer", "description": "the number of URLs that have been clicked for this sender in the last 30 days", "example": 50 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent for this sender in the last 30 days", "example": 30 } } }, "last_60_days": { "type": "object", "description": "stats for this sender in the last 60 days", "properties": { "sent": { "type": "integer", "description": "the number of emails sent for this sender in the last 60 days", "example": 600 }, "hard_bounces": { "type": "integer", "description": "the number of emails hard bounced for this sender in the last 60 days", "example": 15 }, "soft_bounces": { "type": "integer", "description": "the number of emails soft bounced for this sender in the last 60 days", "example": 5 }, "rejects": { "type": "integer", "description": "the number of emails rejected for sending this sender in the last 60 days", "example": 2 }, "complaints": { "type": "integer", "description": "the number of spam complaints for this sender in the last 60 days", "example": 1 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes for this sender in the last 60 days", "example": 0 }, "opens": { "type": "integer", "description": "the number of times emails have been opened for this sender in the last 60 days", "example": 100 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent for this sender in the last 60 days", "example": 75 }, "clicks": { "type": "integer", "description": "the number of URLs that have been clicked for this sender in the last 60 days", "example": 50 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent for this sender in the last 60 days", "example": 30 } } }, "last_90_days": { "type": "object", "description": "stats for this sender in the last 90 days", "properties": { "sent": { "type": "integer", "description": "the number of emails sent for this sender in the last 90 days", "example": 900 }, "hard_bounces": { "type": "integer", "description": "the number of emails hard bounced for this sender in the last 90 days", "example": 5 }, "soft_bounces": { "type": "integer", "description": "the number of emails soft bounced for this sender in the last 90 days", "example": 10 }, "rejects": { "type": "integer", "description": "the number of emails rejected for sending this sender in the last 90 days", "example": 2 }, "complaints": { "type": "integer", "description": "the number of spam complaints for this sender in the last 90 days", "example": 1 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes for this sender in the last 90 days", "example": 0 }, "opens": { "type": "integer", "description": "the number of times emails have been opened for this sender in the last 90 days", "example": 100 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent for this sender in the last 90 days", "example": 80 }, "clicks": { "type": "integer", "description": "the number of URLs that have been clicked for this sender in the last 90 days", "example": 50 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent for this sender in the last 90 days", "example": 30 } } } } } } } } }, "deprecated": false } }, "/senders/time-series": { "post": { "x-custom-config": { "methodNameCamel": "timeSeries", "methodNameSnake": "time_series" }, "summary": "View sender history", "description": "Return the recent history (hourly stats for the last 30 days) for a sender.", "operationId": "postSendersTimeSeries", "tags": [ "senders" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "address" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "address": { "type": "string", "description": "the email address of the sender", "format": "email" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "the array of history information", "items": { "type": "object", "description": "the stats for a single hour", "properties": { "time": { "type": "string", "format": "date-time", "description": "the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format", "example": "2023-01-01 15:00:00" }, "sent": { "type": "integer", "description": "the number of emails that were sent during the hour", "example": 100 }, "hard_bounces": { "type": "integer", "description": "the number of emails that hard bounced during the hour", "example": 5 }, "soft_bounces": { "type": "integer", "description": "the number of emails that soft bounced during the hour", "example": 2 }, "rejects": { "type": "integer", "description": "the number of emails that were rejected during the hour", "example": 1 }, "complaints": { "type": "integer", "description": "the number of spam complaints received during the hour", "example": 0 }, "opens": { "type": "integer", "description": "the number of emails opened during the hour", "example": 80 }, "unique_opens": { "type": "integer", "description": "the number of unique opens generated by messages sent during the hour", "example": 50 }, "clicks": { "type": "integer", "description": "the number of tracked URLs clicked during the hour", "example": 30 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks generated by messages sent during the hour", "example": 20 } } } } } }, "deprecated": false } }, "/subaccounts/list": { "post": { "x-custom-config": { "methodNameCamel": "list", "methodNameSnake": "list" }, "summary": "List subaccounts", "description": "Get the list of subaccounts defined for the account, optionally filtered by a prefix.", "operationId": "postSubaccountsList", "tags": [ "subaccounts" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "q": { "type": "string", "description": "an optional prefix to filter the subaccounts' ids and names" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "the subaccounts for the account, up to a maximum of 1,000", "items": { "type": "object", "description": "the individual subaccount info", "properties": { "id": { "type": "string", "description": "a unique indentifier for the subaccount", "example": "my_subaccount_id" }, "name": { "type": "string", "description": "an optional display name for the subaccount", "example": "My Subaccount" }, "custom_quota": { "type": "integer", "description": "an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation", "example": 500 }, "status": { "type": "string", "description": "the current sending status of the subaccount", "enum": [ "active", "paused" ], "example": "active" }, "reputation": { "type": "integer", "description": "the subaccount's current reputation on a scale from 0 to 100", "minimum": 0, "maximum": 100, "example": 95 }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-15 12:00:00" }, "first_sent_at": { "type": "string", "format": "date-time", "description": "the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-20 15:31:00" }, "sent_weekly": { "type": "integer", "description": "the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)", "example": 1500 }, "sent_monthly": { "type": "integer", "description": "the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)", "example": 6000 }, "sent_total": { "type": "integer", "description": "the number of emails the subaccount has sent since it was created", "example": 10000 } } } } } }, "deprecated": false } }, "/subaccounts/add": { "post": { "x-custom-config": { "methodNameCamel": "add", "methodNameSnake": "add" }, "summary": "Add subaccount", "description": "Add a new subaccount.", "operationId": "postSubaccountsAdd", "tags": [ "subaccounts" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "id" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "id": { "type": "string", "description": "a unique identifier for the subaccount to be used in sending calls", "maxLength": 255 }, "name": { "type": "string", "description": "an optional display name to further identify the subaccount", "maxLength": 1024 }, "notes": { "type": "string", "description": "optional extra text to associate with the subaccount" }, "custom_quota": { "type": "integer", "description": "an optional manual hourly quota for the subaccount. If not specified, Mandrill will manage this based on reputation", "minimum": 0 } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the information saved about the new subaccount", "properties": { "id": { "type": "string", "description": "a unique indentifier for the subaccount", "example": "my_subaccount_id" }, "name": { "type": "string", "description": "an optional display name for the subaccount", "example": "My Subaccount" }, "custom_quota": { "type": "integer", "description": "an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation", "example": 500 }, "status": { "type": "string", "description": "the current sending status of the subaccount", "enum": [ "active", "paused" ], "example": "active" }, "reputation": { "type": "integer", "description": "the subaccount's current reputation on a scale from 0 to 100", "minimum": 0, "maximum": 100, "example": 50 }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-15 12:00:00" }, "first_sent_at": { "type": "string", "format": "date-time", "description": "the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-20 15:31:00" }, "sent_weekly": { "type": "integer", "description": "the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)", "example": 0 }, "sent_monthly": { "type": "integer", "description": "the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)", "example": 0 }, "sent_total": { "type": "integer", "description": "the number of emails the subaccount has sent since it was created", "example": 0 } } } } }, "deprecated": false } }, "/subaccounts/info": { "post": { "x-custom-config": { "methodNameCamel": "info", "methodNameSnake": "info" }, "summary": "Get subaccount info", "description": "Given the ID of an existing subaccount, return the data about it.", "operationId": "postSubaccountsInfo", "tags": [ "subaccounts" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "id" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "id": { "type": "string", "description": "the unique identifier of the subaccount to query" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the information about the subaccount", "properties": { "id": { "type": "string", "description": "a unique indentifier for the subaccount", "example": "my_subaccount_id" }, "name": { "type": "string", "description": "an optional display name for the subaccount", "example": "My Subaccount" }, "notes": { "type": "string", "description": "optional extra text to associate with the subaccount", "example": "This is my subaccount for order receipts" }, "custom_quota": { "type": "integer", "description": "an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation", "example": 500 }, "status": { "type": "string", "description": "the current sending status of the subaccount", "enum": [ "active", "paused" ], "example": "active" }, "reputation": { "type": "integer", "description": "the subaccount's current reputation on a scale from 0 to 100", "minimum": 0, "maximum": 100, "example": 95 }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-15 12:00:00" }, "first_sent_at": { "type": "string", "format": "date-time", "description": "the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-20 15:31:00" }, "sent_weekly": { "type": "integer", "description": "the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)", "example": 1500 }, "sent_monthly": { "type": "integer", "description": "the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)", "example": 6000 }, "sent_total": { "type": "integer", "description": "the number of emails the subaccount has sent since it was created", "example": 10000 }, "sent_hourly": { "type": "integer", "description": "the number of emails the subaccount has sent in the last hour", "example": 200 }, "hourly_quota": { "type": "integer", "description": "the current hourly quota for the subaccount, either manual or reputation-based", "example": 500 }, "last_30_days": { "type": "object", "description": "stats for this subaccount in the last 30 days", "properties": { "sent": { "type": "integer", "description": "the number of emails sent for this subaccount in the last 30 days", "example": 300 }, "hard_bounces": { "type": "integer", "description": "the number of emails hard bounced for this subaccount in the last 30 days", "example": 5 }, "soft_bounces": { "type": "integer", "description": "the number of emails soft bounced for this subaccount in the last 30 days", "example": 10 }, "rejects": { "type": "integer", "description": "the number of emails rejected for sending this subaccount in the last 30 days", "example": 2 }, "complaints": { "type": "integer", "description": "the number of spam complaints for this subaccount in the last 30 days", "example": 1 }, "unsubs": { "type": "integer", "description": "the number of unsbuscribes for this subaccount in the last 30 days", "example": 0 }, "opens": { "type": "integer", "description": "the number of times emails have been opened for this subaccount in the last 30 days", "example": 1000 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent for this subaccount in the last 30 days", "example": 800 }, "clicks": { "type": "integer", "description": "the number of URLs that have been clicked for this subaccount in the last 30 days", "example": 500 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent for this subaccount in the last 30 days", "example": 300 } } } } } } }, "deprecated": false } }, "/subaccounts/update": { "post": { "x-custom-config": { "methodNameCamel": "update", "methodNameSnake": "update" }, "summary": "Update subaccount", "description": "Update an existing subaccount.", "operationId": "postSubaccountsUpdate", "tags": [ "subaccounts" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "id" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "id": { "type": "string", "description": "the unique identifier of the subaccount to update" }, "name": { "type": "string", "description": "an optional display name to further identify the subaccount", "maxLength": 1024 }, "notes": { "type": "string", "description": "optional extra text to associate with the subaccount" }, "custom_quota": { "type": "integer", "description": "an optional manual hourly quota for the subaccount. If not specified, Mandrill will manage this based on reputation", "minimum": 0 } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the information for the updated subaccount", "properties": { "id": { "type": "string", "description": "a unique indentifier for the subaccount", "example": "my_subaccount_id" }, "name": { "type": "string", "description": "an optional display name for the subaccount", "example": "My Subaccount" }, "custom_quota": { "type": "integer", "description": "an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation", "example": 500 }, "status": { "type": "string", "description": "the current sending status of the subaccount", "enum": [ "active", "paused" ], "example": "active" }, "reputation": { "type": "integer", "description": "the subaccount's current reputation on a scale from 0 to 100", "minimum": 0, "maximum": 100, "example": 95 }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-15 12:00:00" }, "first_sent_at": { "type": "string", "format": "date-time", "description": "the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-20 15:31:00" }, "sent_weekly": { "type": "integer", "description": "the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)", "example": 1500 }, "sent_monthly": { "type": "integer", "description": "the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)", "example": 6000 }, "sent_total": { "type": "integer", "description": "the number of emails the subaccount has sent since it was created", "example": 10000 } } } } }, "deprecated": false } }, "/subaccounts/delete": { "post": { "x-custom-config": { "methodNameCamel": "delete", "methodNameSnake": "delete" }, "summary": "Delete subaccount", "description": "Delete an existing subaccount. Any email related to the subaccount will be saved, but stats will be removed and any future sending calls to this subaccount will fail.", "operationId": "postSubaccountsDelete", "tags": [ "subaccounts" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "id" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "id": { "type": "string", "description": "the unique identifier of the subaccount to delete" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the information for the deleted subaccount", "properties": { "id": { "type": "string", "description": "a unique indentifier for the subaccount", "example": "my_subaccount_id" }, "name": { "type": "string", "description": "an optional display name for the subaccount", "example": "My Subaccount" }, "custom_quota": { "type": "integer", "description": "an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation", "example": 500 }, "status": { "type": "string", "description": "the current sending status of the subaccount", "enum": [ "active", "paused" ], "example": "active" }, "reputation": { "type": "integer", "description": "the subaccount's current reputation on a scale from 0 to 100", "minimum": 0, "maximum": 100, "example": 95 }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-15 12:00:00" }, "first_sent_at": { "type": "string", "format": "date-time", "description": "the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-20 15:31:00" }, "sent_weekly": { "type": "integer", "description": "the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)", "example": 1500 }, "sent_monthly": { "type": "integer", "description": "the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)", "example": 6000 }, "sent_total": { "type": "integer", "description": "the number of emails the subaccount has sent since it was created", "example": 30000 } } } } }, "deprecated": false } }, "/subaccounts/pause": { "post": { "x-custom-config": { "methodNameCamel": "pause", "methodNameSnake": "pause" }, "summary": "Pause subaccount", "description": "Pause a subaccount's sending. Any future emails delivered to this subaccount will be queued for a maximum of 3 days until the subaccount is resumed.", "operationId": "postSubaccountsPause", "tags": [ "subaccounts" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "id" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "id": { "type": "string", "description": "the unique identifier of the subaccount to pause" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the information for the paused subaccount", "properties": { "id": { "type": "string", "description": "a unique indentifier for the subaccount", "example": "my_subaccount_id" }, "name": { "type": "string", "description": "an optional display name for the subaccount", "example": "My Subaccount" }, "custom_quota": { "type": "integer", "description": "an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation", "example": 500 }, "status": { "type": "string", "description": "the current sending status of the subaccount", "enum": [ "active", "paused" ], "example": "paused" }, "reputation": { "type": "integer", "description": "the subaccount's current reputation on a scale from 0 to 100", "minimum": 0, "maximum": 100, "example": 95 }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-15 12:00:00" }, "first_sent_at": { "type": "string", "format": "date-time", "description": "the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-20 15:31:00" }, "sent_weekly": { "type": "integer", "description": "the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)", "example": 1500 }, "sent_monthly": { "type": "integer", "description": "the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)", "example": 6000 }, "sent_total": { "type": "integer", "description": "the number of emails the subaccount has sent since it was created", "example": 10000 } } } } }, "deprecated": false } }, "/subaccounts/resume": { "post": { "x-custom-config": { "methodNameCamel": "resume", "methodNameSnake": "resume" }, "summary": "Resume subaccount", "description": "Resume a paused subaccount's sending.", "operationId": "postSubaccountsResume", "tags": [ "subaccounts" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "id" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "id": { "type": "string", "description": "the unique identifier of the subaccount to resume" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the information for the resumed subaccount", "properties": { "id": { "type": "string", "description": "a unique indentifier for the subaccount", "example": "my_subaccount_id" }, "name": { "type": "string", "description": "an optional display name for the subaccount", "example": "My Subaccount" }, "custom_quota": { "type": "integer", "description": "an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation", "example": 500 }, "status": { "type": "string", "description": "the current sending status of the subaccount", "enum": [ "active", "paused" ], "example": "active" }, "reputation": { "type": "integer", "description": "the subaccount's current reputation on a scale from 0 to 100", "minimum": 0, "maximum": 100, "example": 95 }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-15 12:00:00" }, "first_sent_at": { "type": "string", "format": "date-time", "description": "the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-20 15:31:00" }, "sent_weekly": { "type": "integer", "description": "the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)", "example": 1500 }, "sent_monthly": { "type": "integer", "description": "the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)", "example": 6000 }, "sent_total": { "type": "integer", "description": "the number of emails the subaccount has sent since it was created", "example": 10000 } } } } }, "deprecated": false } }, "/tags/list": { "post": { "x-custom-config": { "methodNameCamel": "list", "methodNameSnake": "list" }, "summary": "List tags", "description": "Return all of the user-defined tag information.", "operationId": "postTagsList", "tags": [ "tags" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "a list of user-defined tags", "items": { "type": "object", "description": "a user-defined tag", "properties": { "tag": { "type": "string", "description": "the actual tag as a string", "example": "my_tag" }, "reputation": { "type": "integer", "description": "the tag's current reputation on a scale from 0 to 100.", "minimum": 0, "maximum": 100, "example": 95 }, "sent": { "type": "integer", "description": "the total number of messages sent with this tag", "example": 1000 }, "hard_bounces": { "type": "integer", "description": "the total number of hard bounces by messages with this tag", "example": 50 }, "soft_bounces": { "type": "integer", "description": "the total number of soft bounces by messages with this tag", "example": 25 }, "rejects": { "type": "integer", "description": "the total number of rejected messages with this tag", "example": 10 }, "complaints": { "type": "integer", "description": "the total number of spam complaints received for messages with this tag", "example": 5 }, "unsubs": { "type": "integer", "description": "the total number of unsubscribe requests received for messages with this tag", "example": 2 }, "opens": { "type": "integer", "description": "the total number of times messages with this tag have been opened", "example": 5000 }, "clicks": { "type": "integer", "description": "the total number of times tracked URLs in messages with this tag have been clicked", "example": 1000 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent with this tag", "example": 4500 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent with this tag", "example": 900 } } } } } }, "deprecated": false } }, "/tags/delete": { "post": { "x-custom-config": { "methodNameCamel": "delete", "methodNameSnake": "delete" }, "summary": "Delete tag", "description": "Deletes a tag permanently. Deleting a tag removes the tag from any messages that have been sent, and also deletes the tag's stats. There is no way to undo this operation, so use it carefully.", "operationId": "postTagsDelete", "tags": [ "tags" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "tag" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "tag": { "type": "string", "description": "a tag name" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the tag that was deleted", "properties": { "tag": { "type": "string", "description": "the actual tag as a string", "example": "my_tag" }, "reputation": { "type": "integer", "description": "the tag's current reputation on a scale from 0 to 100.", "minimum": 0, "maximum": 100, "example": 95 }, "sent": { "type": "integer", "description": "the total number of messages sent with this tag", "example": 1000 }, "hard_bounces": { "type": "integer", "description": "the total number of hard bounces by messages with this tag", "example": 50 }, "soft_bounces": { "type": "integer", "description": "the total number of soft bounces by messages with this tag", "example": 25 }, "rejects": { "type": "integer", "description": "the total number of rejected messages with this tag", "example": 10 }, "complaints": { "type": "integer", "description": "the total number of spam complaints received for messages with this tag", "example": 5 }, "unsubs": { "type": "integer", "description": "the total number of unsubscribe requests received for messages with this tag", "example": 2 }, "opens": { "type": "integer", "description": "the total number of times messages with this tag have been opened", "example": 100 }, "clicks": { "type": "integer", "description": "the total number of times tracked URLs in messages with this tag have been clicked", "example": 50 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent with this tag", "example": 75 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent with this tag", "example": 30 } } } } }, "deprecated": false } }, "/tags/info": { "post": { "x-custom-config": { "methodNameCamel": "info", "methodNameSnake": "info" }, "summary": "Get tag info", "description": "Return more detailed information about a single tag, including aggregates of recent stats.", "operationId": "postTagsInfo", "tags": [ "tags" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "tag" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "tag": { "type": "string", "description": "an existing tag name" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the detailed information on the tag", "properties": { "tag": { "type": "string", "description": "the actual tag as a string", "example": "my_tag" }, "sent": { "type": "integer", "description": "the total number of messages sent with this tag", "example": 100 }, "hard_bounces": { "type": "integer", "description": "the total number of hard bounces by messages with this tag", "example": 5 }, "soft_bounces": { "type": "integer", "description": "the total number of soft bounces by messages with this tag", "example": 25 }, "rejects": { "type": "integer", "description": "the total number of rejected messages with this tag", "example": 10 }, "complaints": { "type": "integer", "description": "the total number of spam complaints received for messages with this tag", "example": 2 }, "unsubs": { "type": "integer", "description": "the total number of unsubscribe requests received for messages with this tag", "example": 1 }, "opens": { "type": "integer", "description": "the total number of times messages with this tag have been opened", "example": 50 }, "clicks": { "type": "integer", "description": "the total number of times tracked URLs in messages with this tag have been clicked", "example": 25 }, "stats": { "type": "object", "description": "an aggregate summary of the tag's sending stats", "properties": { "today": { "type": "object", "description": "stats with this tag so far today", "properties": { "sent": { "type": "integer", "description": "the number of emails sent with this tag so far today", "example": 10 }, "hard_bounces": { "type": "integer", "description": "the number of emails hard bounced with this tag so far today", "example": 1 }, "soft_bounces": { "type": "integer", "description": "the number of emails soft bounced with this tag so far today", "example": 2 }, "rejects": { "type": "integer", "description": "the number of emails rejected for sending this sender so far today", "example": 1 }, "complaints": { "type": "integer", "description": "the number of spam complaints with this tag so far today", "example": 2 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes with this tag so far today", "example": 1 }, "opens": { "type": "integer", "description": "the number of times emails have been opened with this tag so far today", "example": 50 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent with this tag so far today", "example": 40 }, "clicks": { "type": "integer", "description": "the number of URLs that have been clicked with this tag so far today", "example": 25 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent with this tag so far today", "example": 20 } } }, "last_7_days": { "type": "object", "description": "stats with this tag in the last 7 days", "properties": { "sent": { "type": "integer", "description": "the number of emails sent with this tag in the last 7 days", "example": 70 }, "hard_bounces": { "type": "integer", "description": "the number of emails hard bounced with this tag in the last 7 days", "example": 5 }, "soft_bounces": { "type": "integer", "description": "the number of emails soft bounced with this tag in the last 7 days", "example": 2 }, "rejects": { "type": "integer", "description": "the number of emails rejected for sending this sender in the last 7 days", "example": 1 }, "complaints": { "type": "integer", "description": "the number of spam complaints with this tag in the last 7 days", "example": 2 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes with this tag in the last 7 days", "example": 1 }, "opens": { "type": "integer", "description": "the number of times emails have been opened with this tag in the last 7 days", "example": 50 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent with this tag in the last 7 days", "example": 40 }, "clicks": { "type": "integer", "description": "the number of URLs that have been clicked with this tag in the last 7 days", "example": 70 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent with this tag in the last 7 days", "example": 60 } } }, "last_30_days": { "type": "object", "description": "stats with this tag in the last 30 days", "properties": { "sent": { "type": "integer", "description": "the number of emails sent with this tag in the last 30 days", "example": 300 }, "hard_bounces": { "type": "integer", "description": "the number of emails hard bounced with this tag in the last 30 days", "example": 50 }, "soft_bounces": { "type": "integer", "description": "the number of emails soft bounced with this tag in the last 30 days", "example": 25 }, "rejects": { "type": "integer", "description": "the number of emails rejected for sending this sender in the last 30 days", "example": 10 }, "complaints": { "type": "integer", "description": "the number of spam complaints with this tag in the last 30 days", "example": 5 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes with this tag in the last 30 days", "example": 1 }, "opens": { "type": "integer", "description": "the number of times emails have been opened with this tag in the last 30 days", "example": 100 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent with this tag in the last 30 days", "example": 80 }, "clicks": { "type": "integer", "description": "the number of URLs that have been clicked with this tag in the last 30 days", "example": 60 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent with this tag in the last 30 days", "example": 50 } } }, "last_60_days": { "type": "object", "description": "stats with this tag in the last 60 days", "properties": { "sent": { "type": "integer", "description": "the number of emails sent with this tag in the last 60 days", "example": 600 }, "hard_bounces": { "type": "integer", "description": "the number of emails hard bounced with this tag in the last 60 days", "example": 25 }, "soft_bounces": { "type": "integer", "description": "the number of emails soft bounced with this tag in the last 60 days", "example": 10 }, "rejects": { "type": "integer", "description": "the number of emails rejected for sending this sender in the last 60 days", "example": 5 }, "complaints": { "type": "integer", "description": "the number of spam complaints with this tag in the last 60 days", "example": 2 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes with this tag in the last 60 days", "example": 1 }, "opens": { "type": "integer", "description": "the number of times emails have been opened with this tag in the last 60 days", "example": 100 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent with this tag in the last 60 days", "example": 80 }, "clicks": { "type": "integer", "description": "the number of URLs that have been clicked with this tag in the last 60 days", "example": 50 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent with this tag in the last 60 days", "example": 40 } } }, "last_90_days": { "type": "object", "description": "stats with this tag in the last 90 days", "properties": { "sent": { "type": "integer", "description": "the number of emails sent with this tag in the last 90 days", "example": 900 }, "hard_bounces": { "type": "integer", "description": "the number of emails hard bounced with this tag in the last 90 days", "example": 10 }, "soft_bounces": { "type": "integer", "description": "the number of emails soft bounced with this tag in the last 90 days", "example": 5 }, "rejects": { "type": "integer", "description": "the number of emails rejected for sending this sender in the last 90 days", "example": 2 }, "complaints": { "type": "integer", "description": "the number of spam complaints with this tag in the last 90 days", "example": 1 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes with this tag in the last 90 days", "example": 0 }, "opens": { "type": "integer", "description": "the number of times emails have been opened with this tag in the last 90 days", "example": 100 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent with this tag in the last 90 days", "example": 80 }, "clicks": { "type": "integer", "description": "the number of URLs that have been clicked with this tag in the last 90 days", "example": 50 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent with this tag in the last 90 days", "example": 40 } } } } } } } } }, "deprecated": false } }, "/tags/time-series": { "post": { "x-custom-config": { "methodNameCamel": "timeSeries", "methodNameSnake": "time_series" }, "summary": "View tag history", "description": "Return the recent history (hourly stats for the last 30 days) for a tag.", "operationId": "postTagsTimeSeries", "tags": [ "tags" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "tag" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "tag": { "type": "string", "description": "an existing tag name" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "the array of history information", "items": { "type": "object", "description": "the stats for a single hour", "properties": { "time": { "type": "string", "format": "date-time", "description": "the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format", "example": "2025-08-01 13:00:00" }, "sent": { "type": "integer", "description": "the number of emails that were sent during the hour", "example": 10 }, "hard_bounces": { "type": "integer", "description": "the number of emails that hard bounced during the hour", "example": 1 }, "soft_bounces": { "type": "integer", "description": "the number of emails that soft bounced during the hour", "example": 0 }, "rejects": { "type": "integer", "description": "the number of emails that were rejected during the hour", "example": 0 }, "complaints": { "type": "integer", "description": "the number of spam complaints received during the hour", "example": 0 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes received during the hour", "example": 0 }, "opens": { "type": "integer", "description": "the number of emails opened during the hour", "example": 5 }, "unique_opens": { "type": "integer", "description": "the number of unique opens generated by messages sent during the hour", "example": 4 }, "clicks": { "type": "integer", "description": "the number of tracked URLs clicked during the hour", "example": 3 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks generated by messages sent during the hour", "example": 2 } } } } } }, "deprecated": false } }, "/tags/all-time-series": { "post": { "x-custom-config": { "methodNameCamel": "allTimeSeries", "methodNameSnake": "all_time_series" }, "summary": "View all tags history", "description": "Return the recent history (hourly stats for the last 30 days) for all tags.", "operationId": "postTagsAllTimeSeries", "tags": [ "tags" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "the array of history information", "items": { "type": "object", "description": "the stats for a single hour", "properties": { "time": { "type": "string", "format": "date-time", "description": "the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format", "example": "2025-08-01 13:00:00" }, "sent": { "type": "integer", "description": "the number of emails that were sent during the hour", "example": 100 }, "hard_bounces": { "type": "integer", "description": "the number of emails that hard bounced during the hour", "example": 2 }, "soft_bounces": { "type": "integer", "description": "the number of emails that soft bounced during the hour", "example": 5 }, "rejects": { "type": "integer", "description": "the number of emails that were rejected during the hour", "example": 1 }, "complaints": { "type": "integer", "description": "the number of spam complaints received during the hour", "example": 0 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes received during the hour", "example": 2 }, "opens": { "type": "integer", "description": "the number of emails opened during the hour", "example": 20 }, "unique_opens": { "type": "integer", "description": "the number of unique opens generated by messages sent during the hour", "example": 10 }, "clicks": { "type": "integer", "description": "the number of tracked URLs clicked during the hour", "example": 12 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks generated by messages sent during the hour", "example": 10 } } } } } }, "deprecated": false } }, "/templates/add": { "post": { "x-custom-config": { "methodNameCamel": "add", "methodNameSnake": "add" }, "summary": "Add template", "description": "Add a new template.", "operationId": "postTemplatesAdd", "tags": [ "templates" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "name" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "name": { "type": "string", "description": "the name for the new template - must be unique" }, "from_email": { "type": "string", "description": "a default sending address for emails sent using this template", "format": "email" }, "from_name": { "type": "string", "description": "a default from name to be used" }, "subject": { "type": "string", "description": "a default subject line to be used" }, "code": { "type": "string", "description": "the HTML code for the template with mc:edit attributes for the editable elements" }, "text": { "type": "string", "description": "a default text part to be used when sending with this template" }, "publish": { "type": "boolean", "description": "set to false to add a draft template without publishing" }, "labels": { "type": "array", "description": "an optional array of up to 10 labels to use for filtering templates", "maxItems": 10, "items": { "type": "string", "description": "a single label", "maxLength": 100 } } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the information saved about the new template", "properties": { "slug": { "type": "string", "description": "the immutable unique code name of the template", "example": "unique_template_slug" }, "name": { "type": "string", "description": "the name of the template", "example": "My Template" }, "labels": { "type": "array", "description": "the list of labels applied to the template", "items": { "type": "string", "description": "a single label", "example": "my_label" } }, "code": { "type": "string", "description": "the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version", "example": "

Hello

" }, "subject": { "type": "string", "description": "the subject line of the template, if provided - draft version", "example": "Welcome to Our Service" }, "from_email": { "type": "string", "description": "the default sender address for the template, if provided - draft version", "example": "sender@example.com" }, "from_name": { "type": "string", "description": "the default sender from name for the template, if provided - draft version", "example": "Sender Name" }, "text": { "type": "string", "description": "the default text part of messages sent with the template, if provided - draft version", "example": "This is the plain text version of the email." }, "publish_name": { "type": "string", "description": "the same as the template name - kept as a separate field for backwards compatibility", "example": "My Template" }, "publish_code": { "type": "string", "description": "the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published", "example": "

Hello

" }, "publish_subject": { "type": "string", "description": "the subject line of the template, if provided", "example": "Welcome to Our Service" }, "publish_from_email": { "type": "string", "format": "email", "description": "the default sender address for the template, if provided", "example": "sender@example.com" }, "publish_from_name": { "type": "string", "description": "the default sender from name for the template, if provided", "example": "Sender Name" }, "publish_text": { "type": "string", "description": "the default text part of messages sent with the template, if provided", "example": "This is the plain text version of the email." }, "published_at": { "type": "string", "format": "date-time", "description": "the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published", "example": "2025-04-29 13:00:00" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:30:00" }, "is_broken_template": { "type": "boolean", "description": "indicates if the template is malformed or corrupt", "example": false } } } } }, "deprecated": false } }, "/templates/info": { "post": { "x-custom-config": { "methodNameCamel": "info", "methodNameSnake": "info" }, "summary": "Get template info", "description": "Get the information for an existing template.", "operationId": "postTemplatesInfo", "tags": [ "templates" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "name" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "name": { "type": "string", "description": "the immutable name of an existing template" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the requested template information", "properties": { "slug": { "type": "string", "description": "the immutable unique code name of the template", "example": "unique_template_slug" }, "name": { "type": "string", "description": "the name of the template", "example": "My Template" }, "labels": { "type": "array", "description": "the list of labels applied to the template", "items": { "type": "string", "description": "a single label", "example": "my_label" } }, "code": { "type": "string", "description": "the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version", "example": "

Hello

" }, "subject": { "type": "string", "description": "the subject line of the template, if provided - draft version", "example": "Welcome to Our Service" }, "from_email": { "type": "string", "description": "the default sender address for the template, if provided - draft version", "example": "sender@example.com" }, "from_name": { "type": "string", "description": "the default sender from name for the template, if provided - draft version", "example": "Sender Name" }, "text": { "type": "string", "description": "the default text part of messages sent with the template, if provided - draft version", "example": "This is the plain text version of the email." }, "publish_name": { "type": "string", "description": "the same as the template name - kept as a separate field for backwards compatibility", "example": "My Template" }, "publish_code": { "type": "string", "description": "the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published", "example": "

Hello

" }, "publish_subject": { "type": "string", "description": "the subject line of the template, if provided", "example": "Welcome to Our Service" }, "publish_from_email": { "type": "string", "format": "email", "description": "the default sender address for the template, if provided", "example": "sender@example.com" }, "publish_from_name": { "type": "string", "description": "the default sender from name for the template, if provided", "example": "Sender Name" }, "publish_text": { "type": "string", "description": "the default text part of messages sent with the template, if provided", "example": "This is the plain text version of the email." }, "published_at": { "type": "string", "format": "date-time", "description": "the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published", "example": "2025-04-29 13:00:00" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:30:00" }, "is_broken_template": { "type": "boolean", "description": "indicates if the template is malformed or corrupt", "example": false } } } } }, "deprecated": false } }, "/templates/update": { "post": { "x-custom-config": { "methodNameCamel": "update", "methodNameSnake": "update" }, "summary": "Update template", "description": "Update the code for an existing template. If null is provided for any fields, the values will remain unchanged.", "operationId": "postTemplatesUpdate", "tags": [ "templates" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "name" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "name": { "type": "string", "description": "the immutable name of an existing template" }, "from_email": { "type": "string", "description": "the new default sending address", "format": "email" }, "from_name": { "type": "string", "description": "the new default from name" }, "subject": { "type": "string", "description": "the new default subject line" }, "code": { "type": "string", "description": "the new code for the template" }, "text": { "type": "string", "description": "the new default text part to be used" }, "publish": { "type": "boolean", "description": "set to false to update the draft version of the template without publishing" }, "labels": { "type": "array", "description": "an optional array of up to 10 labels to use for filtering templates", "maxItems": 10, "items": { "type": "string", "description": "a single label", "maxLength": 100 } } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the template that was updated", "properties": { "slug": { "type": "string", "description": "the immutable unique code name of the template", "example": "unique_template_slug" }, "name": { "type": "string", "description": "the name of the template", "example": "My Template" }, "labels": { "type": "array", "description": "the list of labels applied to the template", "items": { "type": "string", "description": "a single label", "example": "my_label" } }, "code": { "type": "string", "description": "the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version", "example": "

Hello

" }, "subject": { "type": "string", "description": "the subject line of the template, if provided - draft version", "example": "Welcome to Our Service" }, "from_email": { "type": "string", "description": "the default sender address for the template, if provided - draft version", "example": "sender@example.com" }, "from_name": { "type": "string", "description": "the default sender from name for the template, if provided - draft version", "example": "Sender Name" }, "text": { "type": "string", "description": "the default text part of messages sent with the template, if provided - draft version", "example": "This is the plain text version of the email." }, "publish_name": { "type": "string", "description": "the same as the template name - kept as a separate field for backwards compatibility", "example": "My Template" }, "publish_code": { "type": "string", "description": "the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published", "example": "

Hello

" }, "publish_subject": { "type": "string", "description": "the subject line of the template, if provided", "example": "Welcome to Our Service" }, "publish_from_email": { "type": "string", "format": "email", "description": "the default sender address for the template, if provided", "example": "sender@example.com" }, "publish_from_name": { "type": "string", "description": "the default sender from name for the template, if provided", "example": "Sender Name" }, "publish_text": { "type": "string", "description": "the default text part of messages sent with the template, if provided", "example": "This is the plain text version of the email." }, "published_at": { "type": "string", "format": "date-time", "description": "the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published", "example": "2025-04-29 13:00:00" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:30:00" }, "is_broken_template": { "type": "boolean", "description": "indicates if the template is malformed or corrupt", "example": false } } } } }, "deprecated": false } }, "/templates/publish": { "post": { "x-custom-config": { "methodNameCamel": "publish", "methodNameSnake": "publish" }, "summary": "Publish template content", "description": "Publish the content for the template. Any new messages sent using this template will start using the content that was previously in draft.", "operationId": "postTemplatesPublish", "tags": [ "templates" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "name" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "name": { "type": "string", "description": "the immutable name of an existing template" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the template that was published", "properties": { "slug": { "type": "string", "description": "the immutable unique code name of the template", "example": "unique_template_slug" }, "name": { "type": "string", "description": "the name of the template", "example": "My Template" }, "labels": { "type": "array", "description": "the list of labels applied to the template", "items": { "type": "string", "description": "a single label", "example": "my_label" } }, "code": { "type": "string", "description": "the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version", "example": "

Hello

" }, "subject": { "type": "string", "description": "the subject line of the template, if provided - draft version", "example": "Welcome to Our Service" }, "from_email": { "type": "string", "description": "the default sender address for the template, if provided - draft version", "example": "sender@example.com" }, "from_name": { "type": "string", "description": "the default sender from name for the template, if provided - draft version", "example": "Sender Name" }, "text": { "type": "string", "description": "the default text part of messages sent with the template, if provided - draft version", "example": "Hello, welcome to our service!" }, "publish_name": { "type": "string", "description": "the same as the template name - kept as a separate field for backwards compatibility", "example": "My Template" }, "publish_code": { "type": "string", "description": "the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published", "example": "

Hello

" }, "publish_subject": { "type": "string", "description": "the subject line of the template, if provided", "example": "Welcome to Our Service" }, "publish_from_email": { "type": "string", "format": "email", "description": "the default sender address for the template, if provided", "example": "sender@example.com" }, "publish_from_name": { "type": "string", "description": "the default sender from name for the template, if provided", "example": "Sender Name" }, "publish_text": { "type": "string", "description": "the default text part of messages sent with the template, if provided", "example": "Hello, welcome to our service!" }, "published_at": { "type": "string", "format": "date-time", "description": "the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published", "example": "2025-04-29 13:00:00" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:30:00" }, "is_broken_template": { "type": "boolean", "description": "indicates if the template is malformed or corrupt", "example": false } } } } }, "deprecated": false } }, "/templates/delete": { "post": { "x-custom-config": { "methodNameCamel": "delete", "methodNameSnake": "delete" }, "summary": "Delete template", "description": "Delete a template.", "operationId": "postTemplatesDelete", "tags": [ "templates" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "name" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "name": { "type": "string", "description": "the immutable name of an existing template" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the template that was deleted", "properties": { "slug": { "type": "string", "description": "the immutable unique code name of the template", "example": "unique_template_slug" }, "name": { "type": "string", "description": "the name of the template", "example": "My Template" }, "labels": { "type": "array", "description": "the list of labels applied to the template", "items": { "type": "string", "description": "a single label", "example": "my_label" } }, "code": { "type": "string", "description": "the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version", "example": "

Hello

" }, "subject": { "type": "string", "description": "the subject line of the template, if provided - draft version", "example": "Welcome to Our Service" }, "from_email": { "type": "string", "description": "the default sender address for the template, if provided - draft version", "example": "sender@example.com" }, "from_name": { "type": "string", "description": "the default sender from name for the template, if provided - draft version", "example": "Sender Name" }, "text": { "type": "string", "description": "the default text part of messages sent with the template, if provided - draft version", "example": "This is the plain text version of the email." }, "publish_name": { "type": "string", "description": "the same as the template name - kept as a separate field for backwards compatibility", "example": "My Template" }, "publish_code": { "type": "string", "description": "the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published", "example": "

Hello

" }, "publish_subject": { "type": "string", "description": "the subject line of the template, if provided", "example": "Welcome to Our Service" }, "publish_from_email": { "type": "string", "format": "email", "description": "the default sender address for the template, if provided", "example": "sender@example.com" }, "publish_from_name": { "type": "string", "description": "the default sender from name for the template, if provided", "example": "Sender Name" }, "publish_text": { "type": "string", "description": "the default text part of messages sent with the template, if provided", "example": "This is the plain text version of the email." }, "published_at": { "type": "string", "format": "date-time", "description": "the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published", "example": "2025-04-29 13:00:00" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:30:00" }, "is_broken_template": { "type": "boolean", "description": "indicates if the template is malformed or corrupt", "example": false } } } } }, "deprecated": false } }, "/templates/list": { "post": { "x-custom-config": { "methodNameCamel": "list", "methodNameSnake": "list" }, "summary": "List templates", "description": "Return a list of all the templates available to this user.", "operationId": "postTemplatesList", "tags": [ "templates" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "label": { "type": "string", "description": "an optional label to filter the templates" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "an array of structs with information about each template", "items": { "type": "object", "description": "the information on each template in the account", "properties": { "slug": { "type": "string", "description": "the immutable unique code name of the template", "example": "unique_template_slug" }, "name": { "type": "string", "description": "the name of the template", "example": "My Template" }, "labels": { "type": "array", "description": "the list of labels applied to the template", "items": { "type": "string", "description": "a single label", "example": "my_label" } }, "code": { "type": "string", "description": "the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version", "example": "

Hello

" }, "subject": { "type": "string", "description": "the subject line of the template, if provided - draft version", "example": "Welcome to Our Service" }, "from_email": { "type": "string", "description": "the default sender address for the template, if provided - draft version", "example": "sender@example.com" }, "from_name": { "type": "string", "description": "the default sender from name for the template, if provided - draft version", "example": "Sender Name" }, "text": { "type": "string", "description": "the default text part of messages sent with the template, if provided - draft version", "example": "This is the plain text version of the email." }, "publish_name": { "type": "string", "description": "the same as the template name - kept as a separate field for backwards compatibility", "example": "My Template" }, "publish_code": { "type": "string", "description": "the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published", "example": "

Hello

" }, "publish_subject": { "type": "string", "description": "the subject line of the template, if provided", "example": "Welcome to Our Service" }, "publish_from_email": { "type": "string", "format": "email", "description": "the default sender address for the template, if provided", "example": "sender@example.com" }, "publish_from_name": { "type": "string", "description": "the default sender from name for the template, if provided", "example": "Sender Name" }, "publish_text": { "type": "string", "description": "the default text part of messages sent with the template, if provided", "example": "This is the plain text version of the email." }, "published_at": { "type": "string", "format": "date-time", "description": "the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published", "example": "2025-04-29 13:00:00" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:30:00" }, "is_broken_template": { "type": "boolean", "description": "indicates if the template is malformed or corrupt", "example": false } } } } } }, "deprecated": false } }, "/templates/time-series": { "post": { "x-custom-config": { "methodNameCamel": "timeSeries", "methodNameSnake": "time_series" }, "summary": "Get template history", "description": "Return the recent history (hourly stats for the last 30 days) for a template.", "operationId": "postTemplatesTimeSeries", "tags": [ "templates" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "name" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "name": { "type": "string", "description": "the name of an existing template" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "the array of history information", "items": { "type": "object", "description": "the stats for a single hour", "properties": { "time": { "type": "string", "format": "date-time", "description": "the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 14:00:00" }, "sent": { "type": "integer", "description": "the number of emails that were sent during the hour", "example": 1000 }, "hard_bounces": { "type": "integer", "description": "the number of emails that hard bounced during the hour", "example": 10 }, "soft_bounces": { "type": "integer", "description": "the number of emails that soft bounced during the hour", "example": 5 }, "rejects": { "type": "integer", "description": "the number of emails that were rejected during the hour", "example": 2 }, "complaints": { "type": "integer", "description": "the number of spam complaints received during the hour", "example": 1 }, "opens": { "type": "integer", "description": "the number of emails opened during the hour", "example": 800 }, "unique_opens": { "type": "integer", "description": "the number of unique opens generated by messages sent during the hour", "example": 600 }, "clicks": { "type": "integer", "description": "the number of tracked URLs clicked during the hour", "example": 400 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks generated by messages sent during the hour", "example": 300 } } } } } }, "deprecated": false } }, "/templates/render": { "post": { "x-custom-config": { "methodNameCamel": "render", "methodNameSnake": "render" }, "summary": "Render html template", "description": "Inject content and optionally merge fields into a template, returning the HTML that results.", "operationId": "postTemplatesRender", "tags": [ "templates" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "template_name", "template_content" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "template_name": { "type": "string", "description": "the immutable name of a template that exists in the user's account" }, "template_content": { "type": "array", "description": "an array of template content to render. Each item in the array should be a struct with two keys - name: the name of the content block to set the content for, and content: the actual content to put into the block", "items": { "type": "object", "description": "the injection of a single piece of content into a single editable region", "required": [ "name", "content" ], "properties": { "name": { "type": "string", "description": "the name of the mc:edit editable region to inject into" }, "content": { "type": "string", "description": "the content to inject" } } } }, "merge_vars": { "type": "array", "description": "optional merge variables to use for injecting merge field content. If this is not provided, no merge fields will be replaced.", "items": { "type": "object", "description": "a single merge variable", "properties": { "name": { "type": "string", "description": "the merge variable's name. Merge variable names are case-insensitive and may not start with _" }, "content": { "type": "string", "description": "the merge variable's content" } } } } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the result of rendering the given template with the content and merge field values injected", "properties": { "html": { "type": "string", "description": "the rendered HTML as a string", "example": "

Hello, John!

" } } } } }, "deprecated": false } }, "/urls/tracking-domains": { "post": { "x-custom-config": { "methodNameCamel": "trackingDomains", "methodNameSnake": "tracking_domains" }, "summary": "List tracking domains", "description": "Get the list of tracking domains set up for this account.", "operationId": "postUrlsTrackingDomains", "tags": [ "urls" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "the tracking domains and their status", "items": { "type": "object", "description": "the individual tracking domain", "properties": { "domain": { "type": "string", "description": "the tracking domain name", "example": "example.com" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the tracking domain was added as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:00:00" }, "last_tested_at": { "type": "string", "format": "date-time", "description": "when the domain's DNS settings were last tested as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 13:00:00" }, "cname": { "type": "object", "description": "details about the domain's CNAME record", "properties": { "valid": { "type": "boolean", "description": "whether the domain's CNAME record is valid for use with Mandrill", "example": true }, "valid_after": { "type": "string", "description": "when the domain's CNAME record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.", "example": "2025-04-29 14:00:00" }, "error": { "type": "string", "description": "an error describing the CNAME record, or null if the record is correct", "example": " does not match the required CNAME target of mandrillapp.com. Please verify that the target was entered exactly as requested and try again." } } }, "valid_tracking": { "type": "boolean", "description": "whether this domain can be used as a tracking domain for email.", "example": true } } } } } }, "deprecated": false } }, "/urls/add-tracking-domain": { "post": { "x-custom-config": { "methodNameCamel": "addTrackingDomain", "methodNameSnake": "add_tracking_domain" }, "summary": "Add tracking domains", "description": "Add a tracking domain to your account.", "operationId": "postUrlsAddTrackingDomain", "tags": [ "urls" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "domain" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "domain": { "type": "string", "description": "a domain name" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "information about the tracking domain", "properties": { "domain": { "type": "string", "description": "the tracking domain name", "example": "example.com" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the tracking domain was added as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:00:00" }, "last_tested_at": { "type": "string", "format": "date-time", "description": "when the domain's DNS settings were last tested as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 13:00:00" }, "cname": { "type": "object", "description": "details about the domain's CNAME record", "properties": { "valid": { "type": "boolean", "description": "whether the domain's CNAME record is valid for use with Mandrill", "example": false }, "valid_after": { "type": "string", "description": "when the domain's CNAME record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.", "example": "2025-04-29 14:00:00" }, "error": { "type": "string", "description": "an error describing the CNAME record, or null if the record is correct", "example": " does not match the required CNAME target of mandrillapp.com. Please verify that the target was entered exactly as requested and try again." } } }, "valid_tracking": { "type": "boolean", "description": "whether this domain can be used as a tracking domain for email.", "example": false } } } } }, "deprecated": false } }, "/urls/delete-tracking-domain": { "post": { "x-custom-config": { "methodNameCamel": "deleteTrackingDomain", "methodNameSnake": "delete_tracking_domain" }, "summary": "Delete tracking domain", "description": "Deletes an unverified tracking domain from your account. Valid tracking domains cannot be deleted via API and require login confirmation.", "operationId": "postUrlsDeleteTrackingDomain", "tags": [ "urls" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "domain" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "domain": { "type": "string", "description": "the tracking domain name to delete" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "Information about the deleted tracking domain", "properties": { "domain": { "description": "The tracking domain name", "type": "string", "format": "hostname", "example": "track.example.com" }, "created_at": { "description": "When the domain was added to the account (UTC YYYY-MM-DD HH:MM:SS.microseconds)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}\\.\\d+$", "example": "2025-08-15 17:01:12.34214" }, "last_tested_at": { "description": "When the domain was last tested for CNAME configuration (UTC YYYY-MM-DD HH:MM:SS.microseconds)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}\\.\\d+$", "example": "2025-08-15 17:01:12.39638" }, "cname": { "description": "CNAME record verification status and details", "required": [ "valid", "valid_after", "error" ], "properties": { "valid": { "description": "Whether the CNAME record is properly configured", "type": "boolean", "example": false }, "valid_after": { "description": "When the CNAME will be valid (if applicable)", "type": "string", "example": null }, "error": { "description": "an error describing the CNAME record, or null if the record is correct", "example": " does not match the required CNAME target of mandrillapp.com. Please verify that the target was entered exactly as requested and try again." } }, "type": "object" }, "valid_tracking": { "description": "Whether this domain is ready to be used for tracking", "type": "boolean", "example": false } } } } }, "deprecated": false } }, "/urls/check-tracking-domain": { "post": { "x-custom-config": { "methodNameCamel": "checkTrackingDomain", "methodNameSnake": "check_tracking_domain" }, "summary": "Check cname settings", "description": "Checks the CNAME settings for a tracking domain. The domain must have been added already with the add-tracking-domain call.", "operationId": "postUrlsCheckTrackingDomain", "tags": [ "urls" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "domain" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "domain": { "type": "string", "description": "an existing tracking domain name" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "information about the tracking domain", "properties": { "domain": { "type": "string", "description": "the tracking domain name", "example": "example.com" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the tracking domain was added as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:00:00" }, "last_tested_at": { "type": "string", "format": "date-time", "description": "when the domain's DNS settings were last tested as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 13:00:00" }, "cname": { "type": "object", "description": "details about the domain's CNAME record", "properties": { "valid": { "type": "boolean", "description": "whether the domain's CNAME record is valid for use with Mandrill", "example": true }, "valid_after": { "type": "string", "description": "when the domain's CNAME record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.", "example": "2025-04-29 14:00:00" }, "error": { "type": "string", "description": "an error describing the CNAME record, or null if the record is correct", "example": " does not match the required CNAME target of mandrillapp.com. Please verify that the target was entered exactly as requested and try again." } } }, "valid_tracking": { "type": "boolean", "description": "whether this domain can be used as a tracking domain for email.", "example": false } } } } }, "deprecated": false } }, "/users/info": { "post": { "x-custom-config": { "methodNameCamel": "info", "methodNameSnake": "info" }, "summary": "Get user info", "description": "Return the information about the API-connected user.", "operationId": "postUsersInfo", "tags": [ "users" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the user information including username, key, reputation, quota, and historical sending stats", "properties": { "username": { "type": "string", "description": "the username of the user (used for SMTP authentication)", "example": "31352262" }, "created_at": { "type": "string", "description": "the date and time that the user's Mandrill account was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:00:00" }, "public_id": { "type": "string", "description": "a unique, permanent identifier for this user", "example": "pJ9CSLA-VC12xQ9UArlvXA" }, "reputation": { "type": "integer", "description": "the reputation of the user on a scale from 0 to 100, with 75 generally being a \"good\" reputation", "example": 85 }, "hourly_quota": { "type": "integer", "description": "the maximum number of emails Mandrill will deliver for this user each hour. Any emails beyond that will be accepted and queued for later delivery. Users with higher reputations will have higher hourly quotas", "example": 500 }, "backlog": { "type": "integer", "description": "the number of emails that are queued for delivery due to exceeding your monthly or hourly quotas", "example": 0 }, "stats": { "type": "object", "description": "an aggregate summary of the account's sending stats", "properties": { "today": { "type": "object", "description": "stats for this user so far today", "properties": { "sent": { "type": "integer", "description": "the number of emails sent for this user so far today", "example": 100 }, "hard_bounces": { "type": "integer", "description": "the number of emails hard bounced for this user so far today", "example": 2 }, "soft_bounces": { "type": "integer", "description": "the number of emails soft bounced for this user so far today", "example": 1 }, "rejects": { "type": "integer", "description": "the number of emails rejected for sending this sender so far today", "example": 0 }, "complaints": { "type": "integer", "description": "the number of spam complaints for this user so far today", "example": 0 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes for this user so far today", "example": 0 }, "opens": { "type": "integer", "description": "the number of times emails have been opened for this user so far today", "example": 10 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent for this user so far today", "example": 7 }, "clicks": { "type": "integer", "description": "the number of URLs that have been clicked for this user so far today", "example": 8 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent for this user so far today", "example": 5 } } }, "last_7_days": { "type": "object", "description": "stats for this user in the last 7 days", "properties": { "sent": { "type": "integer", "description": "the number of emails sent for this user in the last 7 days", "example": 700 }, "hard_bounces": { "type": "integer", "description": "the number of emails hard bounced for this user in the last 7 days", "example": 2 }, "soft_bounces": { "type": "integer", "description": "the number of emails soft bounced for this user in the last 7 days", "example": 1 }, "rejects": { "type": "integer", "description": "the number of emails rejected for sending this sender in the last 7 days", "example": 0 }, "complaints": { "type": "integer", "description": "the number of spam complaints for this user in the last 7 days", "example": 0 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes for this user in the last 7 days", "example": 0 }, "opens": { "type": "integer", "description": "the number of times emails have been opened for this user in the last 7 days", "example": 50 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent for this user in the last 7 days", "example": 10 }, "clicks": { "type": "integer", "description": "the number of URLs that have been clicked for this user in the last 7 days", "example": 20 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent for this user in the last 7 days", "example": 5 } } }, "last_30_days": { "type": "object", "description": "stats for this user in the last 30 days", "properties": { "sent": { "type": "integer", "description": "the number of emails sent for this user in the last 30 days", "example": 3000 }, "hard_bounces": { "type": "integer", "description": "the number of emails hard bounced for this user in the last 30 days", "example": 100 }, "soft_bounces": { "type": "integer", "description": "the number of emails soft bounced for this user in the last 30 days", "example": 50 }, "rejects": { "type": "integer", "description": "the number of emails rejected for sending this sender in the last 30 days", "example": 5 }, "complaints": { "type": "integer", "description": "the number of spam complaints for this user in the last 30 days", "example": 10 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes for this user in the last 30 days", "example": 2 }, "opens": { "type": "integer", "description": "the number of times emails have been opened for this user in the last 30 days", "example": 500 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent for this user in the last 30 days", "example": 100 }, "clicks": { "type": "integer", "description": "the number of URLs that have been clicked for this user in the last 30 days", "example": 200 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent for this user in the last 30 days", "example": 50 } } }, "last_60_days": { "type": "object", "description": "stats for this user in the last 60 days", "properties": { "sent": { "type": "integer", "description": "the number of emails sent for this user in the last 60 days", "example": 6000 }, "hard_bounces": { "type": "integer", "description": "the number of emails hard bounced for this user in the last 60 days", "example": 100 }, "soft_bounces": { "type": "integer", "description": "the number of emails soft bounced for this user in the last 60 days", "example": 50 }, "rejects": { "type": "integer", "description": "the number of emails rejected for sending this sender in the last 60 days", "example": 10 }, "complaints": { "type": "integer", "description": "the number of spam complaints for this user in the last 60 days", "example": 5 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes for this user in the last 60 days", "example": 2 }, "opens": { "type": "integer", "description": "the number of times emails have been opened for this user in the last 60 days", "example": 300 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent for this user in the last 60 days", "example": 250 }, "clicks": { "type": "integer", "description": "the number of URLs that have been clicked for this user in the last 60 days", "example": 400 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent for this user in the last 60 days", "example": 350 } } }, "last_90_days": { "type": "object", "description": "stats for this user in the last 90 days", "properties": { "sent": { "type": "integer", "description": "the number of emails sent for this user in the last 90 days", "example": 9000 }, "hard_bounces": { "type": "integer", "description": "the number of emails hard bounced for this user in the last 90 days", "example": 100 }, "soft_bounces": { "type": "integer", "description": "the number of emails soft bounced for this user in the last 90 days", "example": 50 }, "rejects": { "type": "integer", "description": "the number of emails rejected for sending this sender in the last 90 days", "example": 10 }, "complaints": { "type": "integer", "description": "the number of spam complaints for this user in the last 90 days", "example": 5 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes for this user in the last 90 days", "example": 2 }, "opens": { "type": "integer", "description": "the number of times emails have been opened for this user in the last 90 days", "example": 4500 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent for this user in the last 90 days", "example": 3000 }, "clicks": { "type": "integer", "description": "the number of URLs that have been clicked for this user in the last 90 days", "example": 1500 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent for this user in the last 90 days", "example": 1000 } } }, "all_time": { "type": "object", "description": "tats for the lifetime of the user's account", "properties": { "sent": { "type": "integer", "description": "the number of emails sent in the lifetime of the user's account", "example": 12345 }, "hard_bounces": { "type": "integer", "description": "the number of emails hard bounced in the lifetime of the user's account", "example": 100 }, "soft_bounces": { "type": "integer", "description": "the number of emails soft bounced in the lifetime of the user's account", "example": 50 }, "rejects": { "type": "integer", "description": "the number of emails rejected for sending this user so far today", "example": 5 }, "complaints": { "type": "integer", "description": "the number of spam complaints in the lifetime of the user's account", "example": 10 }, "unsubs": { "type": "integer", "description": "the number of unsubscribes in the lifetime of the user's account", "example": 2 }, "opens": { "type": "integer", "description": "the number of times emails have been opened in the lifetime of the user's account", "example": 4500 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent in the lifetime of the user's account", "example": 3000 }, "clicks": { "type": "integer", "description": "the number of URLs that have been clicked in the lifetime of the user's account", "example": 1500 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent in the lifetime of the user's account", "example": 1000 } } } } } } } } }, "deprecated": false } }, "/users/ping": { "post": { "x-custom-config": { "methodNameCamel": "ping", "methodNameSnake": "ping" }, "summary": "Ping", "description": "Validate an API key and respond to a ping.", "operationId": "postUsersPing", "tags": [ "users" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "string", "description": "the string \"PONG!\"", "example": "PONG!" } } }, "deprecated": false } }, "/users/ping2": { "post": { "x-custom-config": { "methodNameCamel": "ping2", "methodNameSnake": "ping2" }, "summary": "Ping 2", "description": "Validate an API key and respond to a ping (JSON parser version).", "operationId": "postUsersPing2", "tags": [ "users" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "a struct with one key \"PING\" with a static value \"PONG!\"", "properties": { "PING": { "type": "string", "description": "a simple pong response", "example": "PONG!" } } } } }, "deprecated": false } }, "/users/senders": { "post": { "x-custom-config": { "methodNameCamel": "senders", "methodNameSnake": "senders" }, "summary": "List account senders", "description": "Return the senders that have tried to use this account, both verified and unverified.", "operationId": "postUsersSenders", "tags": [ "users" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "an array of sender data, one for each sending addresses used by the account", "items": { "type": "object", "description": "the information on each sending address in the account", "properties": { "address": { "type": "string", "format": "email", "description": "the sender's email address", "example": "sender@example.com" }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the sender was first seen by Mandrill as a UTC date string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:00:00" }, "sent": { "type": "integer", "description": "the total number of messages sent by this sender", "example": 12135 }, "hard_bounces": { "type": "integer", "description": "the total number of hard bounces by messages by this sender", "example": 678 }, "soft_bounces": { "type": "integer", "description": "the total number of soft bounces by messages by this sender", "example": 123 }, "rejects": { "type": "integer", "description": "the total number of rejected messages by this sender", "example": 4 }, "complaints": { "type": "integer", "description": "the total number of spam complaints received for messages by this sender", "example": 2 }, "unsubs": { "type": "integer", "description": "the total number of unsubscribe requests received for messages by this sender", "example": 1 }, "opens": { "type": "integer", "description": "the total number of times messages by this sender have been opened", "example": 5678 }, "clicks": { "type": "integer", "description": "the total number of times tracked URLs in messages by this sender have been clicked", "example": 2435 }, "unique_opens": { "type": "integer", "description": "the number of unique opens for emails sent for this sender", "example": 4451 }, "unique_clicks": { "type": "integer", "description": "the number of unique clicks for emails sent for this sender", "example": 3416 } } } } } }, "deprecated": false } }, "/webhooks/list": { "post": { "x-custom-config": { "methodNameCamel": "list", "methodNameSnake": "list" }, "summary": "List webhooks", "description": "Get the list of all webhooks defined on the account.", "operationId": "postWebhooksList", "tags": [ "webhooks" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "the webhooks associated with the account", "items": { "type": "object", "description": "the individual webhook info", "properties": { "id": { "type": "integer", "description": "a unique integer indentifier for the webhook", "example": 1131 }, "url": { "type": "string", "description": "The URL that the event data will be posted to", "example": "http://example.com/webhook" }, "description": { "type": "string", "description": "a description of the webhook", "example": "My webhook" }, "auth_key": { "type": "string", "description": "the key used to requests for this webhook", "example": "UHeOnTqMBMGqAEMadhA6xQ" }, "events": { "type": "array", "description": "The message events that will be posted to the hook", "items": { "type": "string", "description": "the individual message event", "enum": [ "send", "hard_bounce", "soft_bounce", "open", "click", "spam", "unsub", "reject" ], "example": "send" } }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the webhook was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:00:00" }, "last_sent_at": { "type": "string", "format": "date-time", "description": "the date and time that the webhook last successfully received events as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 14:00:00" }, "batches_sent": { "type": "integer", "description": "the number of event batches that have ever been sent to this webhook", "example": 4105 }, "events_sent": { "type": "integer", "description": "the total number of events that have ever been sent to this webhook", "example": 10000 }, "last_error": { "type": "string", "description": "if we've ever gotten an error trying to post to this webhook, the last error that we've seen", "example": "Connection timed out" } } } } } }, "deprecated": false } }, "/webhooks/add": { "post": { "x-custom-config": { "methodNameCamel": "add", "methodNameSnake": "add" }, "summary": "Add webhook", "description": "Add a new webhook.", "operationId": "postWebhooksAdd", "tags": [ "webhooks" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "url" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "url": { "type": "string", "description": "the URL to POST batches of events" }, "description": { "type": "string", "description": "an optional description of the webhook" }, "events": { "type": "array", "description": "an optional list of events that will be posted to the webhook", "items": { "type": "object", "description": "the individual event to listen for", "enum": [ "send", "hard_bounce", "soft_bounce", "open", "click", "spam", "unsub", "reject", "blacklist", "whitelist" ] } } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the information saved about the new webhook", "properties": { "id": { "type": "integer", "description": "a unique integer indentifier for the webhook", "example": 1131 }, "url": { "type": "string", "description": "The URL that the event data will be posted to", "example": "http://example.com/webhook" }, "description": { "type": "string", "description": "a description of the webhook", "example": "My webhook" }, "auth_key": { "type": "string", "description": "the key used to requests for this webhook", "example": "UHeOnTqMBMGqAEMadhA6xQ" }, "events": { "type": "array", "description": "The message events that will be posted to the hook", "items": { "type": "string", "description": "the individual message event", "enum": [ "send", "hard_bounce", "soft_bounce", "open", "click", "spam", "unsub", "reject" ], "example": "send" } }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the webhook was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:00:00" }, "last_sent_at": { "type": "string", "format": "date-time", "description": "the date and time that the webhook last successfully received events as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 14:00:00" }, "batches_sent": { "type": "integer", "description": "the number of event batches that have ever been sent to this webhook", "example": 0 }, "events_sent": { "type": "integer", "description": "the total number of events that have ever been sent to this webhook", "example": 0 }, "last_error": { "type": "string", "description": "if we've ever gotten an error trying to post to this webhook, the last error that we've seen", "example": "Connection timed out" } } } } }, "deprecated": false } }, "/webhooks/info": { "post": { "x-custom-config": { "methodNameCamel": "info", "methodNameSnake": "info" }, "summary": "Get webhook info", "description": "Given the ID of an existing webhook, return the data about it.", "operationId": "postWebhooksInfo", "tags": [ "webhooks" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "id" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "id": { "type": "integer", "description": "the unique identifier of a webhook belonging to this account" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the information about the webhook", "properties": { "id": { "type": "integer", "description": "a unique integer indentifier for the webhook", "example": 1131 }, "url": { "type": "string", "description": "The URL that the event data will be posted to", "example": "http://example.com/webhook" }, "description": { "type": "string", "description": "a description of the webhook", "example": "My webhook" }, "auth_key": { "type": "string", "description": "the key used to requests for this webhook", "example": "UHeOnTqMBMGqAEMadhA6xQ" }, "events": { "type": "array", "description": "The message events that will be posted to the hook", "items": { "type": "string", "description": "the individual message event", "enum": [ "send", "hard_bounce", "soft_bounce", "open", "click", "spam", "unsub", "reject" ], "example": "send" } }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the webhook was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:00:00" }, "last_sent_at": { "type": "string", "format": "date-time", "description": "the date and time that the webhook last successfully received events as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 14:00:00" }, "batches_sent": { "type": "integer", "description": "the number of event batches that have ever been sent to this webhook", "example": 12 }, "events_sent": { "type": "integer", "description": "the total number of events that have ever been sent to this webhook", "example": 20 }, "last_error": { "type": "string", "description": "if we've ever gotten an error trying to post to this webhook, the last error that we've seen", "example": "Connection timed out" } } } } }, "deprecated": false } }, "/webhooks/update": { "post": { "x-custom-config": { "methodNameCamel": "update", "methodNameSnake": "update" }, "summary": "Update webhook", "description": "Update an existing webhook.", "operationId": "postWebhooksUpdate", "tags": [ "webhooks" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "id", "url" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "id": { "type": "number", "description": "the unique identifier of a webhook belonging to this account" }, "url": { "type": "string", "description": "the URL to POST batches of events. Requires webhook to exist." }, "description": { "type": "string", "description": "an optional description of the webhook" }, "events": { "type": "array", "description": "an optional list of events that will be posted to the webhook", "items": { "type": "object", "description": "the individual event to listen for", "enum": [ "send", "hard_bounce", "soft_bounce", "open", "click", "spam", "unsub", "reject", "blacklist", "whitelist" ] } } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the information for the updated webhook", "properties": { "id": { "type": "integer", "description": "a unique integer indentifier for the webhook", "example": 1131 }, "url": { "type": "string", "description": "The URL that the event data will be posted to", "example": "http://example.com/webhook" }, "description": { "type": "string", "description": "a description of the webhook", "example": "My webhook" }, "auth_key": { "type": "string", "description": "the key used to requests for this webhook", "example": "UHeOnTqMBMGqAEMadhA6xQ" }, "events": { "type": "array", "description": "The message events that will be posted to the hook", "items": { "type": "string", "description": "the individual message event", "enum": [ "send", "hard_bounce", "soft_bounce", "open", "click", "spam", "unsub", "reject" ], "example": "send" } }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the webhook was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:00:00" }, "last_sent_at": { "type": "string", "format": "date-time", "description": "the date and time that the webhook last successfully received events as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 14:00:00" }, "batches_sent": { "type": "integer", "description": "the number of event batches that have ever been sent to this webhook", "example": 12 }, "events_sent": { "type": "integer", "description": "the total number of events that have ever been sent to this webhook", "example": 100 }, "last_error": { "type": "string", "description": "if we've ever gotten an error trying to post to this webhook, the last error that we've seen", "example": "Connection timed out" } } } } }, "deprecated": false } }, "/webhooks/delete": { "post": { "x-custom-config": { "methodNameCamel": "delete", "methodNameSnake": "delete" }, "summary": "Delete webhook", "description": "Delete an existing webhook.", "operationId": "postWebhooksDelete", "tags": [ "webhooks" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "id" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "id": { "type": "integer", "description": "the unique identifier of a webhook belonging to this account" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "the information for the deleted webhook", "properties": { "id": { "type": "integer", "description": "a unique integer indentifier for the webhook", "example": 1131 }, "url": { "type": "string", "description": "The URL that the event data will be posted to", "example": "http://example.com/webhook" }, "description": { "type": "string", "description": "a description of the webhook", "example": "My webhook" }, "auth_key": { "type": "string", "description": "the key used to requests for this webhook", "example": "UHeOnTqMBMGqAEMadhA6xQ" }, "events": { "type": "array", "description": "The message events that will be posted to the hook", "items": { "type": "string", "description": "the individual message event", "enum": [ "send", "hard_bounce", "soft_bounce", "open", "click", "spam", "unsub", "reject" ], "example": "send" } }, "created_at": { "type": "string", "format": "date-time", "description": "the date and time that the webhook was created as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 12:00:00" }, "last_sent_at": { "type": "string", "format": "date-time", "description": "the date and time that the webhook last successfully received events as a UTC string in YYYY-MM-DD HH:MM:SS format", "example": "2025-04-29 14:00:00" }, "batches_sent": { "type": "integer", "description": "the number of event batches that have ever been sent to this webhook", "example": 100 }, "events_sent": { "type": "integer", "description": "the total number of events that have ever been sent to this webhook", "example": 100 }, "last_error": { "type": "string", "description": "if we've ever gotten an error trying to post to this webhook, the last error that we've seen", "example": "Connection timed out" } } } } }, "deprecated": false } }, "/rejects/add-sms": { "post": { "x-custom-config": { "methodNameCamel": "addSms", "methodNameSnake": "add_sms" }, "summary": "Add phone number to SMS denylist", "description": "Adds a phone number to your SMS rejection denylist. Phone numbers that you add manually will never expire and there is no reputation penalty for removing them from your denylist.", "operationId": "postRejectsAddSms", "tags": [ "rejects" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "phone" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "phone": { "type": "string", "description": "a phone number to block in E.164 format", "example": "+12025551234" }, "comment": { "type": "string", "description": "an optional comment describing the rejection", "example": "Manually blocked due to spam" }, "subaccount": { "type": "string", "description": "an optional unique identifier for the subaccount to limit the denylist entry", "maxLength": 255, "example": "cust-123" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "a status object containing the phone number and the result of the operation", "properties": { "phone": { "type": "string", "description": "the phone number you provided", "example": "+12025551234" }, "added": { "type": "boolean", "description": "whether the operation succeeded" }, "subaccount": { "type": "string", "description": "the subaccount denylist the phone number was added to, if any", "example": "cust-123" } } } } }, "deprecated": false } }, "/rejects/list-sms": { "post": { "x-custom-config": { "methodNameCamel": "listSms", "methodNameSnake": "list_sms" }, "summary": "List SMS denylist entries", "description": "Retrieves your SMS rejection denylist. You can provide a phone number to limit the results. Returns up to 1000 results. By default, entries that have expired are excluded from the results; set include_expired to true to include them.", "operationId": "postRejectsListSms", "tags": [ "rejects" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "phone": { "type": "string", "description": "an optional phone number to search by in E.164 format", "example": "+12025551234" }, "include_expired": { "type": "boolean", "description": "whether to include rejections that have already expired", "example": false }, "subaccount": { "type": "string", "description": "an optional unique identifier for the subaccount to limit the denylist", "maxLength": 255, "example": "cust-123" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "up to 1000 SMS denylist entries", "items": { "type": "object", "properties": { "phone": { "type": "string", "description": "the phone number on the denylist", "example": "+12025551234" }, "created_at": { "type": "string", "description": "the date and time that the entry was created", "example": "2023-01-15 10:30:00" }, "expires_at": { "type": "string", "description": "the date and time that the entry expires", "example": "2023-02-15 10:30:00" }, "expired": { "type": "boolean", "description": "whether the entry has expired", "example": false }, "subaccount": { "type": "string", "description": "the subaccount that the entry belongs to", "example": "cust-123" } } } } } }, "deprecated": false } }, "/rejects/delete-sms": { "post": { "x-custom-config": { "methodNameCamel": "deleteSms", "methodNameSnake": "delete_sms" }, "summary": "Delete phone number from SMS denylist", "description": "Deletes an SMS rejection. There is no limit to how many rejections you can remove from your denylist, but keep in mind that each deletion has an affect on your reputation.", "operationId": "postRejectsDeleteSms", "tags": [ "rejects" ], "parameters": [ { "name": "body", "in": "body", "description": "", "required": true, "schema": { "type": "object", "required": [ "key", "phone" ], "properties": { "key": { "type": "string", "description": "a valid api key" }, "phone": { "type": "string", "description": "a phone number in E.164 format", "example": "+12025551234" }, "subaccount": { "type": "string", "description": "an optional unique identifier for the subaccount to limit the denylist deletion", "maxLength": 255, "example": "cust-123" } } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "a status object containing the phone number and whether the deletion succeeded", "properties": { "phone": { "type": "string", "description": "the phone number you provided", "example": "+12025551234" }, "deleted": { "type": "boolean", "description": "whether the operation succeeded" }, "subaccount": { "type": "string", "description": "the subaccount denylist the phone number was deleted from, if any", "example": "cust-123" } } } } }, "deprecated": false } } }, "definitions": {} }