API reference
Emails
Send single emails and batches, retrieve an email with its delivery events, list emails and cancel scheduled ones.
Send an email
/api/v1/emailsscope: emails:sendQueues 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_idprovides one. htmlstring- HTML body. Provide
html,textortemplate_id. textstring- Plain-text body. Generated from the HTML when omitted.
template_idstring- Send a stored template. Explicit
subject/html/textoverride 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>"
}'import { HulakiMail } from '@hulakimail/node';
const hulakimail = new HulakiMail(process.env.HULAKIMAIL_API_KEY);
const { id } = await hulakimail.emails.send({
from: 'Acme <[email protected]>',
to: ['[email protected]'],
subject: 'Welcome to Acme',
html: '<p>Thanks for signing up, Ada!</p>',
});<?php
use HulakiMail\HulakiMail;
$hulakimail = new HulakiMail(getenv('HULAKIMAIL_API_KEY'));
$email = $hulakimail->emails->send([
'from' => 'Acme <[email protected]>',
'to' => ['[email protected]'],
'subject' => 'Welcome to Acme',
'html' => '<p>Thanks for signing up, Ada!</p>',
]);import os
import requests
response = requests.post(
"https://hulakimail.com/api/v1/emails",
headers={"Authorization": f"Bearer {os.environ['HULAKIMAIL_API_KEY']}"},
json={
"from": "Acme <[email protected]>",
"to": ["[email protected]"],
"subject": "Welcome to Acme",
"html": "<p>Thanks for signing up, Ada!</p>",
},
)
print(response.json()["data"]["id"]){
"data": {
"id": "msg_01JD3Q8Z4X7M2V9K6T1R5B8N0C",
"status": "queued",
"to": ["[email protected]"],
"created_at": "2026-11-14T09:30:12Z"
}
}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
/api/v1/emails/batchscope: emails:sendQueue 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" } }
]
}'{
"data": [
{ "id": "msg_01JD3Q8Z4X7M2V9K6T1R5B8N0C", "status": "queued" },
{ "id": "msg_01JD3Q8Z4X7M2V9K6T1R5B8N0D", "status": "queued" }
]
}Retrieve an email
/api/v1/emails/{id}scope: emails:readReturns 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
/api/v1/emailsscope: emails:readQuery 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
/api/v1/emails/{id}scope: emails:sendCancels 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.