API Reference

Send a single transactional email.

// Response 200
{
  "id": "a1b2c3d4-e5f6-...",
  "message": "Email queued successfully"
}

// Response 200 — when scheduledAt is set
{
  "id": "a1b2c3d4-e5f6-...",
  "status": "scheduled",
  "scheduledAt": "2026-12-25T09:00:00.000Z",
  "message": "Email scheduled successfully"
}

Template mode — reference a saved template by its slug:

// Request body (template mode — no html field needed)
{
  "from": "hello@mail.yourdomain.com",
  "to": "jane@example.com",
  "template": "welcome-email",
  "variables": { "name": "Jane", "plan": "Starter" }
}
// subject is taken from the template's subject field.
// Add "subject": "..." to the request to override it.

Send up to 100 emails in a single request. The batch is all-or-nothing: every email is validated up front, the whole batch is checked against your monthly and daily limits before any email is queued, and on any failure nothing from the batch is sent.

// Response 200
{
  "queued": 3,
  "ids": ["uuid-1", "uuid-2", "uuid-3"]
}

// Response 422 — one or more emails failed validation; nothing was queued.
// Every invalid item is reported with its zero-based index in emails[].
{
  "error": "Batch validation failed — no emails were queued",
  "errors": [
    { "index": 1, "error": "Sending domain not verified: unverified.com" },
    { "index": 4, "error": "scheduledAt must be a future datetime" }
  ]
}

Limit errors (402 monthly / 429 daily) include canSend — see Errors.

Send a transactional email triggered by a USSD callback. Accepts a phoneNumber field to look up the recipient across all contacts in your account; falls back to a direct to address if supplied instead. Returns a minimal { queued, ref } response optimised for USSD gateway handlers.

// Response 200
{
  "queued": true,
  "ref": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

// Response 404 — phone number not found in contacts
{
  "error": "No contact found for this phone number"
}

See the USSD guide for full examples and gateway integration patterns.

Retrieve a single email by its UUID. Returns the full email record including current delivery status, open/click counts, and timestamps. Tenant-scoped — returns 404 if the ID doesn't belong to your account.

// Response 200
{
  "email": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "from": "hello@mail.yourdomain.com",
    "to": "customer@example.com",
    "subject": "Welcome!",
    "status": "delivered",
    "opensCount": 2,
    "clicksCount": 1,
    "openedAt": "2026-07-05T10:15:00.000Z",
    "clickedAt": "2026-07-05T10:16:00.000Z",
    "sentAt": "2026-07-05T10:00:00.000Z",
    "createdAt": "2026-07-05T09:58:00.000Z",
    "messageId": "0100019a2b3c4d5e-f6a7b8c9-...",
    "provider": "primary"
  }
}

// Response 404
{ "error": "Email not found" }

Status values: "queued" · "scheduled" · "sending" · "sent" · "delivered" · "bounced" · "failed" · "cancelled" · "suppressed" (all recipients on your suppression list — nothing was sent)

Provider values: "primary", or "failover" when the email was delivered through Quolle's failover infrastructure during an incident on the primary path.

Node.js SDK: const email = await quolle.emails.get(id)

Cancel a scheduled email before it is dispatched. Only emails with status "scheduled" can be cancelled — immediate sends are queued for dispatch right away and cannot be recalled. Tenant-scoped — returns 404 if the ID doesn't belong to your account.

// Response 200
{
  "message": "Scheduled email cancelled"
}

// Response 400 — email exists but is not in "scheduled" status
{ "error": "Email is not scheduled" }

// Response 404
{ "error": "Email not found" }

Node.js SDK: const { message } = await quolle.emails.cancel(id)

List all available plans with features and pricing in Naira. Public — no auth required.

// Response 200
{
  "plans": [
    {
      "id": "uuid",
      "name": "Starter",
      "monthlyLimit": 3000,
      "priceNaira": 0,
      "paystackPlanCode": null,
      "retentionDays": 7,
      "features": ["3,000 emails/mo", "API access", "SMTP access", "1 domain", "Email templates", "Analytics dashboard"]
    },
    {
      "id": "uuid",
      "name": "Growth",
      "monthlyLimit": 50000,
      "priceNaira": 20000,
      "paystackPlanCode": "PLN_abc123",
      "retentionDays": 90,
      "features": ["50,000 emails/mo", "API access", "SMTP access", "5 domains", "Email templates", "Analytics dashboard", "Webhook support"]
    }
  ]
}

How many contacts would actually receive this, before you send. Always call this first — the reachable count is smaller than the list size once unsubscribes, bounces and topic opt-outs are removed.

// Request
{ "listId": "uuid", "topicId": "uuid" }   // topicId optional

// Response 200
{
  "recipientCount": 940,
  "sample": ["ada@example.com", "grace@example.com"],
  "note": "Unsubscribed, bounced and complained addresses are excluded, along with anyone who opted out of this topic."
}

Send one copy to yourself to check how it renders.

The recipient must be an address your account controls: your login email, an active team member, or a mailbox on one of your verified domains. Limited to 20 per hour. Both limits exist because this is the one marketing path that accepts a free-form recipient and skips the transactional quota — without them it would be unmetered mail to anyone.

// Request — same body as a campaign, plus `to`
{ "listId": "uuid", "to": "you@yourdomain.com", "from": "hello@mail.yourdomain.com",
  "subject": "August newsletter", "html": "<h1>Hello</h1>" }

// Response 200
{ "id": "uuid", "message": "Test sent to you@yourdomain.com" }

// Response 403
{ "error": "Test sends can only go to your own account email, an active team member, or an address on one of your verified domains." }

Create a campaign. With scheduledAt it waits; without, it dispatches immediately.

// Response 200 — immediate
{ "id": "uuid", "status": "sending", "recipientCount": 940 }

// Response 200 — scheduled
{ "id": "uuid", "status": "scheduled", "scheduledAt": "2026-09-01T09:00:00.000Z", "estimatedRecipients": 940 }

// Response 402 — no marketing subscription
{ "error": "A marketing plan is required to send campaigns", "upgrade": "marketing" }

// Response 400 — nobody reachable
{ "error": "Nobody on that list is subscribed to this topic" }

List your campaigns with engagement figures.

Open and click rates are measured against delivered mail, not everything attempted, so bounced addresses cannot flatter a rate.

One campaign with per-recipient results (first 1,000).

// Response 200
{
  "id": "uuid",
  "subject": "August newsletter",
  "status": "sent",
  "sentAt": "2026-08-15T10:00:00.000Z",
  "stats": { "recipients": 940, "delivered": 928, "bounced": 12, "opened": 402, "clicked": 88,
             "openRate": 43.3, "clickRate": 9.5 },
  "recipients": [
    { "email": "ada@example.com", "status": "delivered", "openedAt": "2026-08-15T10:12:00.000Z",
      "clickedAt": null, "opensCount": 2, "clicksCount": 0 }
  ]
}

Cancel a draft or scheduled campaign. One already sending cannot be recalled — the mail is with the provider.

Your marketing subscription and current usage.

// Response 200
{
  "plan": { "id": "uuid", "name": "Marketing 10k", "priceNaira": 25000, "maxMarketingContacts": 10000 },
  "subscribed": true,
  "contacts": 4210,
  "contactLimit": 10000,
  "monthlySendLimit": null,   // null = unmetered (all paid tiers)
  "sentThisMonth": 0,
  "unlimitedSends": true,
  "periodEnd": "2026-09-14T00:00:00.000Z",
  "paused": false,
  "pausedReason": null
}

The free marketing tier is the one exception to unmetered sending: it carries a monthly campaign-email cap, reported here as monthlySendLimit.

List your contact lists with a contact count for each.

// Response 200
{
  "lists": [
    { "id": "uuid", "name": "Newsletter subscribers", "contactCount": 1240, "createdAt": "2026-08-01T09:00:00.000Z" }
  ]
}

Create a contact list.

// Request
{ "name": "Newsletter subscribers" }

// Response 201
{ "id": "uuid", "name": "Newsletter subscribers" }

Delete a list and every contact on it. Not reversible.

Suppression records survive this. Anyone who unsubscribed stays suppressed even after their contact row is gone — deleting a list is not a way to reset consent.

Bulk-import contacts from a CSV file. Send as multipart/form-data with the file in a file field.

Recognised columns: email (required), firstName, lastName, phone. Existing addresses on the list are skipped rather than duplicated, and previously unsubscribed addresses stay unsubscribed — re-importing someone is not consent, and treating it as such is how senders end up on blocklists.

curl -X POST https://api.quolle.com/v1/contacts/LIST_ID/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@contacts.csv"

// Response 200
{ "imported": 812, "skipped": 14, "invalid": 3 }

// Response 403 — billing state blocks imports before the file is even parsed
{ "error": "Your subscription is past due — resolve billing to import contacts." }

Add a contact to a list. firstName and lastName are available as merge tags in campaigns.

// Request
{
  "email": "ada@example.com",
  "firstName": "Ada",
  "lastName": "Okafor",
  "metadata": { "plan": "pro" }
}

// Response 201
{ "id": "uuid", "email": "ada@example.com" }

List contacts on a list, including their unsubscribe state.

Remove a contact from a list.

Note: deleting a contact does not delete their suppression record. Someone who unsubscribed stays suppressed even if you re-import them — re-importing an address is not consent.

List your topics. Pass ?includeArchived=true to include archived ones.

// Response 200
{
  "topics": [
    {
      "id": "uuid",
      "name": "Product updates",
      "description": "New features and improvements, roughly monthly",
      "position": 0,
      "archived": false,
      "optedOut": 37,
      "createdAt": "2026-08-15T09:00:00.000Z"
    }
  ]
}

optedOut is how many contacts have opted out of this topic specifically. A number climbing faster than your others is telling you something about that topic, not about your list.

Create a topic. Names must be unique within your account.

// Request
{ "name": "Product updates", "description": "New features and improvements, roughly monthly" }

// Response 201
{ "id": "uuid", "name": "Product updates", "message": "Topic \"Product updates\" created" }

// Response 409
{ "error": "You already have a topic with that name" }

Update a topic’s name, description, position, or archived state. All fields optional.

Archives the topic — it stops being sendable and disappears from the preference centre.

Deliberately not a hard delete. Opt-out records outlive the topic, so restoring it later cannot silently re-subscribe the people who asked to leave it.

// Response 200
{ "message": "\"Offers\" archived. Existing opt-outs are kept, so restoring it won't re-subscribe anyone." }

The contacts who opted out of this topic, most recent first. Up to 500.

// Response 200
{
  "topic": { "id": "uuid", "name": "Product updates" },
  "optOuts": [
    { "email": "ada@example.com", "name": "Ada Okafor", "optedOutAt": "2026-08-14T18:22:00.000Z" }
  ]
}