[00]Reference

API reference

The MailHaap REST API reference, rendered from the published OpenAPI specification: every operation, every field, every error, with a runnable example.

Base URL

https://api.mailhaap.com/v1

Version 2026-08-0112 operations across 6 resourcesDownload openapi.yaml

Versioning

The URL carries the major version. Behavioural changes ship behind a dated version header (Mailhaap-Version: 2026-08-01) that is pinned per workspace at signup, so nothing changes under you. Breaking changes get a new date, and the previous two dates stay supported for at least twelve months with deprecation headers.

POST/emailssendEmail

Send an email

Parameters

Parameters for sendEmail
Field	Type	Notes
Idempotency-Key	string	Replays within 24 hours return the original response.header

Request body

Request body for sendEmail
Field	Type	Notes
fromreq	string	e.g. ABC Emlak <[email protected]>
toreq	oneOf
cc	array<string>
bcc	array<string>
reply_to	array<string>
subject	string	max 998 chars
html	string
text	string
template_id	string
template_data	object
attachments	array<object>	max 20 items
attachments[].filenamereq	string	max 255 chars
attachments[].content	string
attachments[].url	string	uri
attachments[].content_type	string
attachments[].content_id	string	For inline images (cid:)
headers	object
tags	array<object>
tags[].namereq	string
tags[].valuereq	string	max 128 chars
tracking	object
tracking.opens	boolean	default false
tracking.clicks	boolean	default true
scheduled_at	string	date-time

Response · 202 Accepted and queued

Response body for sendEmail
Field	Type	Notes
id	string	e.g. msg_01J8XQ7M2K9PQRSTUV
status	"queued" \| "scheduled"
created_at	string	date-time

Errors

401 · Missing, invalid or revoked API key
403 · Insufficient scope, IP not allowed, or tenant suspended
422 · Validation or business rule failure
429 · Too many requests

Example

POST /emails

curl -X POST https://api.mailhaap.com/v1/emails \
  -H "Authorization: Bearer $MAILHAAP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "from": "ABC Emlak <[email protected]>",
    "to": "value"
  }'

POST/emails/batchsendEmailBatch

Send up to 100 emails in one request

Parameters

Parameters for sendEmailBatch
Field	Type	Notes
Idempotency-Key	string	Replays within 24 hours return the original response.header

Response · 207 Per-item results in request order

Response body for sendEmailBatch
Field	Type	Notes
data	array<object>

Example

POST /emails/batch

curl -X POST https://api.mailhaap.com/v1/emails/batch \
  -H "Authorization: Bearer $MAILHAAP_API_KEY"

GET/emails/{id}getEmail

Retrieve a message and its event timeline

Parameters

Parameters for getEmail
Field	Type	Notes
idreq	string	path

Response · 200 OK

Response body for getEmail
Field	Type	Notes
id	string
status	"queued" \| "scheduled" \| "sending" \| "sent" \| "delivered" \| "bounced" \| "complained" \| "failed" \| "suppressed" \| "cancelled"
plane	"mailbox" \| "transactional" \| "campaign"
from	string
to	array<string>
subject	string
tags	array<object>
tags[].namereq	string
tags[].valuereq	string	max 128 chars
created_at	string	date-time
events	array<object>
events[].type	"email.queued" \| "email.sent" \| "email.delivered" \| "email.deferred" \| "email.bounced" \| "email.complained" \| "email.opened" \| "email.clicked" \| "email.failed" \| "contact.unsubscribed" \| "domain.verified" \| "domain.degraded" \| "campaign.completed" \| "campaign.throttled" \| "campaign.blocked" \| "tenant.limit_reached"
events[].occurred_at	string	date-time
events[].detail	object

Errors

404 · Not found (also returned for resources belonging to another tenant)

Example

GET /emails/{id}

curl -X GET https://api.mailhaap.com/v1/emails/msg_01J8XQ7M2K9PQRSTUV \
  -H "Authorization: Bearer $MAILHAAP_API_KEY"

POST/emails/{id}/cancelcancelEmail

Cancel a queued or scheduled message

Parameters

Parameters for cancelEmail
Field	Type	Notes
idreq	string	path

Response · 200 Cancelled

No body.

Errors

422 · Validation or business rule failure

Example

POST /emails/{id}/cancel

curl -X POST https://api.mailhaap.com/v1/emails/msg_01J8XQ7M2K9PQRSTUV/cancel \
  -H "Authorization: Bearer $MAILHAAP_API_KEY"