On this page

REST API & Webhook Reference

Public developer reference for sending email, triggering automations, managing recipient consent, and receiving signed lifecycle webhooks. No sign-in is required to read these docs.

Authentication

Create API key

Public integration requests require a live or test API key in the Authorization header.

bash

1curl https://api.hivsy.com/api/emails \2  -H "Authorization: Bearer hsl_live_<your_key>" \3  -H "Content-Type: application/json" \4  -d '{ ... }'

Keys may be scoped to one domain. A scoped key can only send from that verified domain. Dashboard endpoints use the signed-in browser session and are outside this public API contract.

Base URL

https

1https://api.hivsy.com

Integration endpoints accept and return JSON. Email sends use /api/emails; the Resend-compatible alias /emails has the same request and response contract.

Errors

JSON errors contain an error field. Rate-limit responses may be plain text.

json

1{2  "error": "invalid from address"3}

`400`	Invalid JSON, addresses, parameters, or a suppressed recipient
`401`	Missing or invalid API key
`402`	Insufficient email credits
`403`	Domain-scoped key does not match the sender domain
`404`	Referenced template or audience not found
`409`	An idempotency key was reused with a different request
`413`	JSON request body exceeds the endpoint limit
`423`	Sending is paused for this account
`429`	Rate limit exceeded
`500`	Unexpected server error

DNS prerequisite: verify the domain's SPF and DKIM records before using outbound lifecycle, open, or click events. To use email.received, also publish the inbound MX record shown on the domain's DNS Records tab.

Rate limits

API-key endpoints share a limit of 300 requests per minute per key. Requests above the limit return HTTP 429. Use an idempotency key when retrying sends or automation events.

OpenAPI specification

The OpenAPI 3.1 contract is public and suitable for SDK generators, API clients, and validation tools.

https

1https://api.hivsy.com/api/openapi.yaml

Download the YAML specification or use /api/docs as the stable discovery route.

Send email

POST/api/emails

Queue an email from a verified domain. The response contains the email ID and initial status.

Parameter	Type	Description	Required
`from`	`string`	Sender on a verified domain; display names are allowed.	Yes
`to`	`string[]`	At least one address. Maximum 50 unique recipients total across To, CC, and BCC; duplicate mailboxes are rejected case-insensitively.	Yes
`subject`	`string`	Required unless supplied by the selected template; at most 998 bytes.	No
`html`	`string`	HTML body, up to 1 MiB. Required unless text or a template body is available.	No
`text`	`string`	Plain-text body, up to 100 KiB. Required unless HTML or a template body is available.	No
`cc`	`string[]`	CC recipients.	No
`bcc`	`string[]`	BCC recipients.	No
`reply_to`	`string`	Reply-To address.	No
`headers`	`object`	Up to 20 custom `X-*` headers; each pair is limited to 1 KiB.	No
`attachments`	`object[]`	Up to 10 attachments, each at most 5 MiB decoded. The complete JSON request, including base64 expansion, must remain under 10 MiB.	No
`template_id`	`uuid`	Saved template owned by this account.	No
`variables`	`object`	String values for exact `{{key}}` placeholders. HTML values are escaped.	No
`scheduled_at`	`date-time`	Future RFC 3339 timestamp, no more than one year ahead.	No

Attachment object

Parameter	Type	Description	Required
`filename`	`string`	File name of at most 255 UTF-8 bytes, without path separators or control characters.	Yes
`content_type`	`string`	Optional valid MIME media type such as `application/pdf`.	No
`content`	`string`	Base64-encoded file content.	Yes

bash

1curl -X POST https://api.hivsy.com/api/emails \2  -H "Authorization: Bearer hsl_live_<key>" \3  -H "Content-Type: application/json" \4  -d '{5    "from": "Hivsy <hello@yourdomain.com>",6    "to": ["ada@example.com"],7    "subject": "Your order is confirmed",8    "html": "<p>Thanks for your order, <strong>Ada</strong>!</p>",9    "text": "Thanks for your order!"10  }'

json

1{2  "id": "5266867d-9729-49c5-adef-06c2113f292a",3  "status": "queued"4}

javascript

1const response = await fetch('https://api.hivsy.com/api/emails', {2  method: 'POST',3  headers: {4    Authorization: 'Bearer hsl_live_<key>',5    'Content-Type': 'application/json',6  },7  body: JSON.stringify({8    from: 'hello@yourdomain.com',9    to: ['ada@example.com'],10    subject: 'Welcome',11    html: '<p>Hello!</p>',12  }),13});14const { id, status } = await response.json();

Schedule delivery

Set scheduled_at to a future RFC 3339 timestamp. Scheduled sends can be queued up to one year ahead and consume credits when accepted.

bash

1curl -X POST https://api.hivsy.com/api/emails \2  -H "Authorization: Bearer $HIVSY_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "from": "you@yourdomain.com",6    "to": ["ada@example.com"],7    "subject": "Your scheduled update",8    "text": "This was scheduled in advance.",9    "scheduled_at": "2027-01-15T15:00:00Z"10  }'

Delivery retries

Temporary SMTP failures, including 4xx replies and connection errors, are retried for up to five days from the time the message becomes eligible for delivery. The first retry is scheduled after about 30 minutes, the second after about two hours, and later attempts every two to three hours. Small timing jitter prevents a recovering provider from receiving every delayed message at once.

Permanent 5xx replies are not retried. Only a permanent RCPT TO rejection is treated as a hard bounce and suppresses that exact recipient; sender, authentication, TLS, and message-transfer failures never suppress recipients.

For direct delivery to more than one recipient domain, Hivsy records each destination that already accepted the message. A later retry sends only to the remaining recipients, preventing duplicate delivery to successful domains.

The email detail page records every attempt with its SMTP stage, reply code, enhanced status, exact provider response, recipients already accepted, next retry time, and final retry deadline. Use the Events tab or copy the diagnostic report when investigating a failure.

Idempotency

Send an Idempotency-Key header of at most 256 characters. Reusing the key returns the original email with HTTP 200 and idempotent_replay: true instead of creating a duplicate.

bash

1curl -X POST https://api.hivsy.com/api/emails \2  -H "Authorization: Bearer $HIVSY_API_KEY" \3  -H "Idempotency-Key: order-1234-receipt" \4  -H "Content-Type: application/json" \5  -d '{ "from": "you@yourdomain.com", "to": ["ada@example.com"], "subject": "Receipt", "text": "Thanks!" }'

Test mode

Test keys use the hsl_test_ prefix. They validate the same payload, record the email with status sent, and return HTTP 202 without delivering or consuming credits.

Suppressions

Hard bounces and one-click unsubscribes populate the suppression list automatically. A send containing any suppressed recipient is rejected with HTTP 400 before credits are charged. Manage suppressions in the dashboard or call POST /api/unsubscribe from an integration.

Trigger an automation event

POST/api/events

Record an application event and trigger active automations whose configured event name matches.

Include an Idempotency-Key header (up to 256 characters) when retrying. The same key and payload reuse the original event and automation runs; a changed payload returns HTTP 409.

Parameter	Type	Description	Required
`name`	`string`	Automation trigger name, for example `user.signed_up`.	Yes
`contact_email`	`string`	Recipient used by matching email automations. Without it, the event is recorded and each matching email run is marked failed with a diagnostic.	No
`data`	`object`	Application-defined metadata. The complete event request is limited to 1 MiB.	No

bash

1curl -X POST https://api.hivsy.com/api/events \2  -H "Authorization: Bearer $HIVSY_API_KEY" \3  -H "Idempotency-Key: customer-123-created" \4  -H "Content-Type: application/json" \5  -d '{6    "name": "user.signed_up",7    "contact_email": "ada@example.com",8    "data": { "first_name": "Ada", "plan": "starter" }9  }'

json

1{2  "event_id": "d908ca46-eef2-4572-a9dc-6b33d1842335",3  "automations_triggered": 14}

Unsubscribe a contact

POST/api/unsubscribe

Unsubscribe matching contacts across all owned audiences, or scope the update to one audience.

Parameter	Type	Description	Required
`email`	`string`	Contact email address.	Yes
`audience_id`	`uuid`	Optional owned audience. Omit it to update every audience.	No

bash

1curl -X POST https://api.hivsy.com/api/unsubscribe \2  -H "Authorization: Bearer $HIVSY_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{ "email": "ada@example.com" }'

json

1{2  "unsubscribed": 23}

Webhook delivery

Configure webhook endpoints from a verified domain in the dashboard. Hivsy returns the signing secret when an endpoint is created or its secret is rotated. Store it immediately.

An empty event selection subscribes the endpoint to every event. Hivsy treats any 2xx response as an acknowledgement and retries connection failures or non-2xx responses up to ten times, ending after the final 24-hour retry.

json

1{2  "type": "email.sent",3  "created_at": "2026-08-05T19:14:22Z",4  "data": {5    "email_id": "5266867d-9729-49c5-adef-06c2113f292a",6    "from": "hello@yourdomain.com",7    "to": [8      "ada@example.com"9    ],10    "subject": "Your order is confirmed",11    "created_at": "2026-08-05T19:14:19Z",12    "sent_at": "2026-08-05T19:14:21Z"13  }14}

Webhook event types

Event	Status	Meaning
`email.received`	Live	Inbound email received for a verified domain
`email.sent`	Live	Outbound message accepted by the recipient server
`email.failed`	Live	Outbound delivery permanently failed
`email.delivery_delayed`	Live	A temporary delivery failure will be retried
`email.opened`	Live	Tracking pixel requested by a recipient
`email.clicked`	Live	Tracked link opened by a recipient
`email.suppressed`	Live	Delivery stopped because every recipient was suppressed

Verify webhook signatures

Read the Webhook-Signature header and calculate HMAC-SHA256 over the exact raw request body. The header value is sha256=<lowercase hex digest>.X-Webhook-Signature is also sent for backward compatibility.

Verify the raw bytes before parsing JSON. Re-serializing the payload changes the signature input.

javascript

1import crypto from 'node:crypto';2 3function verifyWebhook(rawBody, signature, secret) {4  if (!signature?.startsWith('sha256=')) return false;5  const actual = signature.slice('sha256='.length);6  const expected = crypto7    .createHmac('sha256', secret)8    .update(rawBody)9    .digest('hex');10  if (actual.length !== expected.length) return false;11  return crypto.timingSafeEqual(12    Buffer.from(actual, 'hex'),13    Buffer.from(expected, 'hex'),14  );15}

python

1import hashlib2import hmac3 4def verify_webhook(raw_body: bytes, signature: str, secret: str) -> bool:5    expected = "sha256=" + hmac.new(6        secret.encode(), raw_body, hashlib.sha2567    ).hexdigest()8    return hmac.compare_digest(signature, expected)