API reference

Every Mailazy product capability is API-accessible. Authentication is two-header (key + secret), responses are JSON, errors are typed.

Base URL

https://api.mailazy.com/api/v1

Authentication

Every request requires two headers:

X-API-Key:    pk_live_xxx
X-API-Secret: sk_live_xxx

X-API-Key identifies your product. Safe to use in non-secret contexts (build logs, error reports).
X-API-Secret proves you own the key. Treat like a password — server-side only.
Keys are scoped to a single product (one product = one tenant). Cross-product calls return 404 as if the resource doesn't exist.
Rotate from Settings → API. Old credentials revoke instantly; mid-flight requests fail with 401.

Super-admin auth (multi-product)

Owners with multiple products can use a super-admin token instead of per-product keys. Set Authorization: Bearer mzy_admin_xxx and add a X-Product-Slug: <slug> header to scope the request. Super-admin auth is required for product CRUD itself.

Response shape

All success responses return JSON with a 2xx status. Errors return JSON with a 4xx/5xx status and an error field:

{
  "error":   "Template not found",
  "code":    "template_not_found",
  "details": { "slug": "non-existent" }        // sometimes
}

Error codes

Status	Meaning
`400`	Malformed request — bad JSON, malformed CSV.
`401`	Missing / invalid API credentials.
`403`	Authenticated but not allowed (e.g. super-admin endpoint with product key).
`404`	Resource doesn't exist — or exists in a different product.
`409`	Conflicting state — e.g. editing a newsletter while it's in `sending`.
`413`	Payload too large — usually a CSV over 5MB or 10k rows.
`422`	Validation failure — zod schema rejected the body. Includes field-level details.
`429`	Rate limit. Always carries a `Retry-After` header.
`500`	Unexpected server error. Includes a `requestId` to share with support.
`502`	Upstream failure (SMTP provider, AI provider). Body includes the upstream message.
`504`	Upstream timeout (60s on AI generation, 30s on SMTP).

Rate limits

Limits are per-product, applied across all endpoints in the namespace:

Namespace	Free	Marketing	Scale
`/send` + SMTP	10/s	100/s	Custom
`/templates/generate` (AI)	20/min	20/min	Custom
`/newsletters/:id/test-send`	10/min/newsletter	10/min/newsletter	10/min/newsletter
`/templates/:id/test-send`	10/min/template	10/min/template	10/min/template
Everything else (CRUD)	30/s	200/s	Custom

Endpoint summary

Send

`POST`	`/send`	Send a transactional email by template slug or inline HTML.
`POST`	`/events`	Emit a product event (triggers automation steps).

Templates

`POST`	`/templates`	Create or new-version a template.
`GET`	`/templates`	List templates (optional `?activeOnly=true`).
`GET`	`/templates/:id`	Read one template (optional `?version=N`).
`POST`	`/templates/generate`	AI-generate a draft from a prompt.
`POST`	`/templates/:id/preview`	Render the template with a real or synthetic contact.
`POST`	`/templates/:id/test-send`	Send to one address; no log row.

Newsletters

`POST`	`/newsletters`	Create draft or scheduled campaign.
`GET`	`/newsletters`	List (filter by status).
`GET`	`/newsletters/:id`	Detail + counts.
`PATCH`	`/newsletters/:id`	Edit (draft/scheduled only).
`POST`	`/newsletters/:id/schedule`	Move draft → scheduled.
`POST`	`/newsletters/:id/send-now`	Set scheduledAt = now().
`POST`	`/newsletters/:id/cancel`	Stop a scheduled or sending campaign.
`DELETE`	`/newsletters/:id`	Delete (draft only).
`GET`	`/newsletters/:id/recipients`	Count + sample of current list membership.
`POST`	`/newsletters/:id/preview`	Render preview.
`POST`	`/newsletters/:id/test-send`	Send test; no log row.

Automations

`POST`	`/automations`	Create a multi-step automation.
`GET`	`/automations`	List automations.
`PATCH`	`/automations/:id`	Edit steps.
`DELETE`	`/automations/:id`	Disable an automation.

Contacts & lists

`POST`	`/contacts`	Create a single contact.
`POST`	`/contacts/import`	Bulk import CSV or JSON.
`GET`	`/contacts`	Search / list contacts.
`POST`	`/lists`	Create a list.
`POST`	`/lists/from-filter`	Materialize a list from a filter.
`GET`	`/lists/filter-preview`	Count + sample for a filter.
`POST`	`/lists/:id/members`	Add contacts to a list.
`DELETE`	`/lists/:id/members/:contactId`	Remove from a list (per-list unsubscribe).
`GET`	`/suppressions`	List suppressions.
`POST`	`/suppressions`	Suppress an address globally.
`DELETE`	`/suppressions/:id`	Un-suppress.

Config & observability

`GET/PUT/DELETE`	`/smtp`	Per-product SMTP/SES config.
`GET/PUT/DELETE`	`/ai-config`	Per-product AI generation config.
`POST`	`/ai-config/test`	Verify AI credentials.
`POST/GET/DELETE`	`/webhooks`	Subscribe / list / unsubscribe webhook endpoints.
`GET`	`/logs`	Send log search.

OpenAPI / Postman

A full OpenAPI 3 spec is served at /api/v1/openapi.json. Import directly into Postman, Insomnia, or your client SDK generator. Postman collection downloads also available at the support email.

SDKs

Official SDKs cover Node, Python, Go, Ruby, PHP, and Java. They wrap auth, retries, and SMTP fallback. See the dashboard Settings → API → SDKs for install commands.