Skip to content

Search documentation

Search pages and sections

API reference

Emails

Send single emails and batches, retrieve an email with its delivery events, list emails and cancel scheduled ones.

Send an email

POST/api/v1/emailsscope: emails:send

Queues an email for delivery and returns 202 Accepted immediately. Delivery happens in the background — follow it with GET /emails/{id} or webhooks.

Body parameters

fromstringrequired
Sender, e.g. Acme <[email protected]>. The domain must be verified in your workspace.
tostring | string[]required
One or more recipients. To, cc and bcc together may contain up to 50 addresses.
subjectstring
Required unless template_id provides one.
htmlstring
HTML body. Provide html, text or template_id.
textstring
Plain-text body. Generated from the HTML when omitted.
template_idstring
Send a stored template. Explicit subject/html/text override it.
variablesobject
Values for {{placeholders}} in the subject and body.
ccstring | string[]
Carbon-copy recipients.
bccstring | string[]
Blind carbon-copy recipients.
reply_tostring | string[]
Reply-To address(es).
headersobject
Custom headers, e.g. {"X-Entity-Ref-ID": "4821"}. Some headers (From, DKIM-Signature…) can’t be overridden.
attachmentsobject[]
See Attachments. Total message size up to 30 MB.
tagsstring[]
Labels for filtering logs and analytics, e.g. ["receipt"].
metadataobject
Your own key/value pairs (strings, numbers, booleans). Returned in webhooks.
scheduled_atstring
ISO 8601 time to send in the future (up to 30 days ahead).
track_opensboolean
Override the domain’s default open tracking.
track_clicksboolean
Override the domain’s default click tracking.
curl https://hulakimail.com/api/v1/emails \
  -H "Authorization: Bearer $HULAKIMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Welcome to Acme",
    "html": "<p>Thanks for signing up, Ada!</p>"
  }'
202 Accepted
{
  "data": {
    "id": "msg_01JD3Q8Z4X7M2V9K6T1R5B8N0C",
    "status": "queued",
    "to": ["[email protected]"],
    "created_at": "2026-11-14T09:30:12Z"
  }
}
Add an Idempotency-Key header so retries never send twice. See Idempotency.

Attachments

filenamestringrequired
Name shown to the recipient, e.g. invoice-4821.pdf.
contentstringrequired
Base64-encoded file content.
content_typestring
MIME type, e.g. application/pdf. Guessed from the filename when omitted.
content_idstring
Embed inline and reference it in HTML as cid:<content_id>.
"attachments": [
  { "filename": "invoice-4821.pdf", "content": "JVBERi0xLjcKJc...", "content_type": "application/pdf" },
  { "filename": "logo.png", "content": "iVBORw0KGgo...", "content_id": "logo" }
]

Executable files (such as .exe, .bat, .js) are rejected.

Scheduling

Set scheduled_at to send later. The response status is scheduled; you can cancel until the send time.

Send a batch

POST/api/v1/emails/batchscope: emails:send

Queue up to 100 emails in one request — each with its own recipients, content and variables. Each email is validated independently, and each counts towards your monthly volume.

curl https://hulakimail.com/api/v1/emails/batch \
  -H "Authorization: Bearer $HULAKIMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      { "from": "Acme <[email protected]>", "to": ["[email protected]"], "template_id": "tpl_01JD…", "variables": { "first_name": "Ada" } },
      { "from": "Acme <[email protected]>", "to": ["[email protected]"], "template_id": "tpl_01JD…", "variables": { "first_name": "Grace" } }
    ]
  }'
202 Accepted
{
  "data": [
    { "id": "msg_01JD3Q8Z4X7M2V9K6T1R5B8N0C", "status": "queued" },
    { "id": "msg_01JD3Q8Z4X7M2V9K6T1R5B8N0D", "status": "queued" }
  ]
}

Retrieve an email

GET/api/v1/emails/{id}scope: emails:read

Returns the email with its current status and every delivery event recorded so far.

{
  "data": {
    "id": "msg_01JD3Q8Z4X7M2V9K6T1R5B8N0C",
    "status": "delivered",
    "from": "Acme <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Welcome to Acme",
    "tags": ["welcome"],
    "metadata": { "user_id": "u_123" },
    "created_at": "2026-11-14T09:30:12Z",
    "sent_at": "2026-11-14T09:30:12Z",
    "events": [
      { "type": "sent", "recipient": "[email protected]", "occurred_at": "2026-11-14T09:30:12Z" },
      { "type": "delivered", "recipient": "[email protected]", "occurred_at": "2026-11-14T09:30:13Z" }
    ]
  }
}

Statuses

queuedstatus
Accepted and waiting to be sent.
scheduledstatus
Waiting for scheduled_at.
sentstatus
Handed to the delivery network.
deliveredstatus
Accepted by the recipient’s mail server.
bouncedstatus
Rejected by the recipient’s server. Hard bounces are added to suppressions.
complainedstatus
The recipient marked the email as spam.
suppressedstatus
Not sent because the recipient is on your suppression list.
failedstatus
Could not be sent (for example, invalid content).
cancelledstatus
A scheduled email you cancelled.

With several recipients, the email’s status reflects the most recent event; per-recipient detail is in events.

List emails

GET/api/v1/emailsscope: emails:read

Query parameters

statusstring
Filter by status, e.g. bounced.
tostring
Filter by recipient address.
tagstring
Filter by tag.
since / untilstring
ISO 8601 bounds on created_at.
page / per_pageinteger
See Pagination.

Emails are returned newest first and only for your plan’s log-retention period.

Cancel a scheduled email

DELETE/api/v1/emails/{id}scope: emails:send

Cancels an email whose status is scheduled. Returns the email with status cancelled, or 409 if it has already been sent.

Something unclear or missing? Tell us.