Skip to main content

​
Field naming per product

The two API products use different casing conventions — this is intentional and stable: Don’t mix them: a from_name sent to the Email API (or a senderEmail to the Marketing API) is silently ignored or rejected.

​
Pagination

List endpoints across the Marketing API use page-based pagination with two required body fields:
page starts at 1. Responses include a total count so you can compute the number of pages. There is no cursor-based pagination.

​
API versions

  • v1 (https://cloudapi.mailercloud.com/v1) — the current Marketing API. All endpoints except one.
  • v2 (https://cloudapi.mailercloud.com/v2) — currently a single endpoint, Create Campaign (v2), which offers more options than the v1 create (pause rules, frequency cap, tag/segment targeting). Both versions are fully supported; v2 is recommended for new integrations that need those capabilities.
  • Email API versioning is expressed in the request body: version: "1.0" (HTML only) or "2.0" (with AMP).

​
Idempotency

The APIs do not currently support idempotency keys, with one exception: the Email API’s metadata.messageId. Reusing the same messageId within 24 hours returns success without sending the message again, so a timed-out send request is safe to retry with the same id. This applies to the HTTP Email API only — SMTP relay assigns its own id per message and has no duplicate detection. Everywhere else, a request that times out client-side may still have been processed. Design batch retries accordingly: prefer confirming state (e.g. campaign exists, contact exists via upsert) over blind re-submission of send requests.

​
SDKs

Plain HTTP/cURL is the officially supported integration path — every endpoint page shows generated examples in cURL, Python, JavaScript, PHP, and Go. There are no official SDK packages at this time; AI-assisted integration is first-class instead (see Use with AI tools).