The LuneaMail API

Getting started

The base URL is https://app.luneamail.com/api/v1. Requests and responses are JSON. Authenticate every request with a workspace API key as a Bearer token: create one in Settings › API keys (admins only). A key belongs to one workspace, so keep it on your server.

Authorization: Bearer $LUNEAMAIL_API_KEY
Content-Type: application/json

Templates are designed in the visual builder or written in HTML with Handlebars: {{name}}, {{#if}}, {{#each}} and {{#if (eq plan "pro")}}. Send one with POST /send.

Errors

Errors come with an HTTP status and a body with a stable error code to branch on and a message written for people. Codes are listed under each endpoint and all together at the end of this page.

{
  "error": "MISSING_VARIABLE",
  "message": "Template rendering failed: \"licenseKey\" not defined in [object Object]"
}

Rate limits

Over a limit, you get 429 RATE_LIMITED with a Retry-After header in seconds. Request bodies can be up to about 4.5 MB, which is why attachments are capped at 3 MB.

Send an email

POST/send

Sends one transactional email (a receipt, license key, password reset or alert) from a template, filled with your data. It needs no contact and doesn't add one.

• templateId is the id in the template's editor address: app.luneamail.com/templates/<templateId>.
• The subject and body take the same {{variables}}. A variable used outside {{#if}} or {{#each}} is required: leave it out and the email isn't sent (MISSING_VARIABLE), so nobody gets a broken one.
• The email goes out from your brand's sender name and address. Until that address's domain is verified, it's sent from LuneaMail's address with your name, and replies go to yours.
• Unsubscribing from marketing doesn't stop transactional email. Addresses that bounced, complained or were dropped are refused (SUPPRESSED).
• Each email counts toward the plan's monthly emails, like campaign email. On Pro and Team, email sent through your own SES or SMTP server doesn't.
• On the Free plan the email carries a small "Made with LuneaMail" line.

curl "https://app.luneamail.com/api/v1/send" \
  -H "Authorization: Bearer $LUNEAMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "cm3p0y...",
    "to": "buyer@company.com",
    "subject": "Your {{product}} license",
    "data": {
      "firstName": "Ana",
      "product": "Pro",
      "licenseKey": "ABCD-1234-EFGH",
      "seats": 5
    }
  }'

Add or update a contact

POST/contacts

Adds a contact for marketing email, or updates one with the same email. Lists are added to, never removed from, and attributes merge into the ones already saved.

• A new contact needs consent: { confirmed: true }, your statement that the person agreed to receive your marketing. Updating an existing contact doesn't.
• Someone who unsubscribed, bounced or complained is added unsubscribed and stays that way.
• The plan's contact limit applies to new contacts (CONTACT_LIMIT).
• A new subscribed contact sends the contact.subscribed webhook.

curl "https://app.luneamail.com/api/v1/contacts" \
  -H "Authorization: Bearer $LUNEAMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ana@company.com",
    "firstName": "Ana",
    "lastName": "Silva",
    "attributes": {
      "plan": "pro",
      "seats": 5
    },
    "lists": [
      "cl8q1v..."
    ],
    "consent": {
      "confirmed": true,
      "source": "Signup form on company.com"
    }
  }'

Look up a contact

GET/contacts?email=

Returns one contact by email, with its attributes and list ids.

curl -X GET "https://app.luneamail.com/api/v1/contacts?email=ana@company.com" \
  -H "Authorization: Bearer $LUNEAMAIL_API_KEY"

Erase a contact

DELETE/contacts?email=

Erases a contact and its events, for a GDPR or CCPA deletion request. An unsubscribe or bounce record for the address is kept, so it's never emailed again.

curl -X DELETE "https://app.luneamail.com/api/v1/contacts?email=ana@company.com" \
  -H "Authorization: Bearer $LUNEAMAIL_API_KEY"

Unsubscribe an address

POST/contacts/unsubscribe

Opts an address out of all marketing email, for example when someone unsubscribes in your own app. It works for addresses that aren't contacts yet, so they can't be added later.

• A contact that was subscribed sends the contact.unsubscribed webhook. Transactional email (POST /send) still reaches them.

curl "https://app.luneamail.com/api/v1/contacts/unsubscribe" \
  -H "Authorization: Bearer $LUNEAMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ana@company.com"
  }'

List your lists

GET/lists

Returns the workspace's lists with their member counts, sorted by name. Use the ids with POST /contacts.

curl -X GET "https://app.luneamail.com/api/v1/lists" \
  -H "Authorization: Bearer $LUNEAMAIL_API_KEY"

Webhooks

LuneaMail tells your server when contacts and campaigns change, so your CRM and app stay in sync.

• Add endpoints in Settings › Webhooks: up to 10 per workspace, each a public HTTPS URL with the events it wants. Each gets its own signing secret.
• Each event is a POST with a JSON body: { id, type, createdAt, workspaceId, data }.
• Answer with any 2xx status within 10 seconds. Redirects aren't followed and count as a failure.
• Failed deliveries are retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours: 8 attempts over about two days.
• After 15 deliveries in a row fail every retry, the endpoint is turned off and your admins get an email. Turn it back on in Settings › Webhooks.
• Send a test event (type ping) from Settings › Webhooks to check an endpoint. It isn't retried.

Verifying signatures

Compute an HMAC-SHA256 of <timestamp>.<raw body> with the endpoint's secret and compare it with the signature in constant time. Use the body exactly as received, before any JSON parsing, and reject timestamps more than five minutes old so a captured request can't be replayed.

import crypto from "node:crypto";

// rawBody: the request body exactly as received
export function verify(rawBody, headers, secret) {
  const ts = headers["x-luneamail-timestamp"];
  const expected = "v1=" + crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");
  const got = headers["x-luneamail-signature"] ?? "";
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && got.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}

All error codes