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/v1All 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.
Scopes
Give each key only the scopes it needs. A request without the required scope gets 403 insufficient_scope.
| Scope | Allows |
|---|---|
| emails:send | Send emails and batches, cancel scheduled emails |
| emails:read | Retrieve and list emails and their events |
| templates:read | List and retrieve templates |
| templates:write | Create, update and delete templates |
| domains:read | List and retrieve domains and their DNS status |
| contacts:read / contacts:write | Read or manage contacts, lists and suppressions |
| campaigns:read | Read campaigns and their statistics |
| webhooks:write | Manage webhook endpoints |
| full_access | Everything 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"
}
}| Status | type | Typical codes |
|---|---|---|
| 400 / 422 | invalid_request_error | validation_failed, domain_not_verified |
| 401 | authentication_error | missing_api_key, invalid_api_key, api_key_revoked, api_key_expired |
| 403 | permission_error | insufficient_scope, ip_not_allowed, workspace_suspended |
| 404 | not_found_error | email_not_found, domain_not_found, template_not_found |
| 409 | conflict_error | idempotency_key_reused, idempotency_in_progress |
| 429 | rate_limit_error | rate_limit_exceeded, quota_exceeded |
| 5xx | api_error | internal_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).
| Plan | Requests / second | Emails / month |
|---|---|---|
| Free | 10 | 3,000 |
| Starter | 50 | 50,000 |
| Pro | 100 | 250,000 |
| Business | 200 | 1,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
| Endpoint | Description |
|---|---|
| POST /emails | Send an email |
| POST /emails/batch | Send up to 100 emails |
| GET /emails/{id} | Retrieve an email and its events |
| GET /emails | List emails |
| /templates | Create, list, update and delete templates |
| /suppressions | Manage the suppression list |
| /domains | List domains and their DNS status |
Something unclear or missing? Tell us.