Skip to content

Search documentation

Search pages and sections

API reference

API overview

Base URL, authentication, request and response format, errors, idempotency, rate limits and pagination for the Hulaki REST API.

Base URL

https://hulakimail.com/api/v1

All requests must use HTTPS. The API is versioned in the path; we only make backwards-compatible changes within v1 (adding fields, endpoints or optional parameters).

Authentication

Authenticate with a workspace API key in the Authorization header. Keys start with hm_live_, are shown once when created, and are stored hashed — if you lose one, create a new key.

curl https://hulakimail.com/api/v1/domains \
  -H "Authorization: Bearer hm_live_..."

Keys can optionally be restricted to a list of IP addresses and given an expiry date. Requests from a suspended workspace are rejected with 403 workspace_suspended.

API keys grant access to your workspace. Keep them on the server — never in browser or mobile app code.

Scopes

Give each key only the scopes it needs. A request without the required scope gets 403 insufficient_scope.

ScopeAllows
emails:sendSend emails and batches, cancel scheduled emails
emails:readRetrieve and list emails and their events
templates:readList and retrieve templates
templates:writeCreate, update and delete templates
domains:readList and retrieve domains and their DNS status
contacts:read / contacts:writeRead or manage contacts, lists and suppressions
campaigns:readRead campaigns and their statistics
webhooks:writeManage webhook endpoints
full_accessEverything above

Requests & responses

Send JSON bodies with Content-Type: application/json. Responses are JSON; single objects are wrapped in a data key. IDs are prefixed strings (msg_…, dom_…, tpl_…) and timestamps are ISO 8601 in UTC.

{
  "data": {
    "id": "dom_01jd3p5w2x8k4m7t1r9b6n0c3q",
    "name": "acme.com",
    "status": "verified"
  }
}

Errors

Errors use conventional HTTP status codes and always have the same shape:

{
  "error": {
    "type": "invalid_request_error",
    "message": "The from address must use a verified domain.",
    "code": "domain_not_verified",
    "param": "from"
  }
}
StatustypeTypical codes
400 / 422invalid_request_errorvalidation_failed, domain_not_verified
401authentication_errormissing_api_key, invalid_api_key, api_key_revoked, api_key_expired
403permission_errorinsufficient_scope, ip_not_allowed, workspace_suspended
404not_found_erroremail_not_found, domain_not_found, template_not_found
409conflict_erroridempotency_key_reused, idempotency_in_progress
429rate_limit_errorrate_limit_exceeded, quota_exceeded
5xxapi_errorinternal_error — safe to retry with the same Idempotency-Key

param is present when the error relates to a specific field. Use code for programmatic handling — messages may change.

Idempotency

Network failures happen. To retry a POST safely, send an Idempotency-Key header with a unique value (a UUID, or your own order ID). If Hulaki has already processed a request with that key, it returns the original response instead of sending again.

curl https://hulakimail.com/api/v1/emails \
  -H "Authorization: Bearer $HULAKIMAIL_API_KEY" \
  -H "Idempotency-Key: order-4821-receipt" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
  • Keys are remembered for 24 hours per workspace.
  • Reusing a key with a different body returns 409 idempotency_key_reused.
  • The Node.js and PHP SDKs generate a key for every send automatically.

Rate limits

Requests are limited per API key, per second, by plan. Monthly sending volume is limited separately (see Limits & quotas).

PlanRequests / secondEmails / month
Free103,000
Starter5050,000
Pro100250,000
Business2001,000,000

Every response includes X-RateLimit-Limit and X-RateLimit-Remaining. When you exceed the limit you get 429 with a Retry-After header (seconds) — wait that long, then retry. Use the batch endpoint to send many emails in one request.

Pagination

List endpoints are paginated. Pass page (from 1) and per_page (max 100). The response includes a meta object:

GET /api/v1/domains?page=2&per_page=25

{
  "data": [ ... ],
  "meta": { "current_page": 2, "last_page": 4, "per_page": 25, "total": 87 }
}

The SDKs provide iterators that walk every page for you.

Endpoints

EndpointDescription
POST /emailsSend an email
POST /emails/batchSend up to 100 emails
GET /emails/{id}Retrieve an email and its events
GET /emailsList emails
/templatesCreate, list, update and delete templates
/suppressionsManage the suppression list
/domainsList domains and their DNS status

Something unclear or missing? Tell us.