LlamaEmailBETA
Developer API

Integrate today.

Send and receive from your domain with the Node SDK or plain REST. Manage domains and mailboxes, and stream delivery events — including inbound mail — into your platform.

Node.js uses the first-party @llamaemail/sdk package in this repo. Other language tabs are REST examples (not separate SDKs).

import { LlamaEmail } from '@llamaemail/sdk';

const llama = new LlamaEmail(process.env.LLAMAEMAIL_API_KEY);

const email = await llama.emails.send({
  from: 'hello@yourdomain.com',
  to: 'friend@example.com',
  subject: 'Hello World',
  html: '<strong>It works.</strong>',
});

console.log(email);

Node SDK

First-party client for emails, domains, mailboxes, and delivery events. Lives in this repository as @llamaemail/sdk (packages/sdk). Not published to the public npm registry yet — use it from the monorepo workspace, or call the same REST endpoints directly.

import { LlamaEmail } from '@llamaemail/sdk';

const llama = new LlamaEmail(process.env.LLAMAEMAIL_API_KEY);

await llama.emails.send({ to: 'friend@example.com', subject: 'Hi', text: 'Hello' });
await llama.domains.list();
await llama.mailboxes.create({
  domain_id: 'your-domain-id',
  local_part: 'ops',
  name: 'Ops',
});
await llama.events.list({ limit: 20 });

Manage in the app

Everything for day-to-day platform ops lives under Settings → Developer API:

  • Create and revoke API keys (sending, receive, or full access)
  • Add HTTPS webhooks for sent, received, bounced, and complained mail
  • Inspect the delivery log (status, attempts, last error)
  • Copy the base URL and open this documentation

Open Developer API

Authentication

Create a key in Settings → Developer API. Choose sending only, receive only, or full access. Keep keys on your server — never in browser JavaScript.

Authorization: Bearer le_live_<publicId>_<secret>
Access Scopes Allows
Sending only send POST /v1/emails, domains, delivery events
Receive only read GET /v1/emails, GET /v1/emails/{id}, domains, delivery events
Full access send + read Send, read, domains, mailboxes, and delivery events. Workspace owners can also create domains and mailboxes.

Send an email

Creates outbound mail through your mailbox. Accepted messages appear in webmail Sent.

POST https://app.llamaemail.com/v1/emails
Field Type Notes
from string Optional. Verified identity on the key’s mailbox.
to string | string[] Required.
cc, bcc string | string[] Optional.
subject string Optional.
text, html string At least one required. Max 100 KB each.
Idempotency-Key UUID header Safe retries. Also idempotency_key in JSON.

Attachments

Optional base64 attachments on send (max 30 files, 10 MB total).

{
  "attachments": [
    {
      "filename": "invoice.pdf",
      "content_type": "application/pdf",
      "content": "<base64>"
    }
  ]
}

List emails

Read inbox or sent for the key’s mailbox.

GET /v1/emails?folder=inbox&limit=20

Get an email

Fetch one message by id (64-character hex).

GET /v1/emails/{id}

Domains

List domains in the API key’s workspace and inspect setup status. Workspace owners with a full-access key can also create a domain (DNS verification still completes in the app). Does not expose verification secrets.

GET /v1/domains
GET /v1/domains/{id}
POST /v1/domains
{ "name": "yourdomain.com" }
{
  "id": "local-domain",
  "object": "domain",
  "name": "yourdomain.com",
  "status": { "stage": "connected", "label": "Connected", "detail": "…" },
  "verified_at": "2026-01-01T00:00:00Z",
  "sending_verified": true,
  "receiving_state": "receiving"
}

Mailboxes

List mailboxes your key’s user can access in the workspace. Workspace owners with full-access keys can create a mailbox on an existing domain.

GET /v1/mailboxes
GET /v1/mailboxes/{id}
POST /v1/mailboxes
{
  "domain_id": "local-domain",
  "local_part": "hello",
  "name": "Hello"
}

Delivery events

Bounce and complaint events for mail sent from this mailbox (matched via provider message id). Prefer webhooks for real-time handling; this endpoint is for polling or debugging.

GET /v1/events?limit=20
{
  "object": "list",
  "data": [
    {
      "id": "…",
      "object": "event",
      "type": "email.bounced",
      "email_id": "…",
      "recipient": "bounce@example.com",
      "bounce_type": "hard",
      "suppressed": true
    }
  ]
}

Webhooks

Add an HTTPS endpoint in Settings → Developer API. We POST signed JSON for email.sent, email.received, email.bounced and email.complained. Delivery attempts appear in the Developer API delivery log.

LlamaEmail-Timestamp: 1717200000
LlamaEmail-Signature: <base64url hmac sha256 of timestamp.payload>

Verify with your signing secret: HMAC-SHA256 of timestamp + '.' + rawBody.

{
  "type": "email.received",
  "created_at": "2026-10-03T04:00:00.000Z",
  "data": {
    "email_id": "…",
    "mailbox_id": "hello",
    "mailbox": "hello@yourdomain.com",
    "from": "customer@example.com",
    "to": ["hello@yourdomain.com"],
    "subject": "Order question",
    "text": "…",
    "received_at": "2026-10-03T04:00:00.000Z"
  }
}

Errors

Errors return JSON shaped like { "error": { "message", "code" } }.

HTTP Code Meaning
401 unauthorized Missing or invalid API key
403 forbidden Missing scope, bad from, or sending suspended
409 conflict Idempotency key reused with a different payload
422 recipient_suppressed Recipient blocked after bounce/complaint
429 sending_limit Workspace send budget exceeded

OpenAPI

Machine-readable spec: /docs/api/openapi.json