API Reference

Create a new account. Returns a JWT token.

// Response 201
{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "customer": { "id": "uuid", "name": "Amara", "email": "amara@example.com" }
}

Authenticate and receive a JWT token.

// Response 200
{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "customer": { "id": "uuid", "name": "Amara", "email": "amara@example.com" }
}

Send a single transactional email.

// Response 202
{
  "id": "a1b2c3d4-e5f6-...",
  "status": "queued",          // or "scheduled" when scheduledAt is set
  "message": "Email queued successfully",
  "scheduledAt": null          // ISO datetime if scheduled, else null
}

Send up to 50 emails in a single request. Each email is queued independently.

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

Get status and details for a specific email.

// Response 200
{
  "id": "a1b2c3d4-...",
  "from": "hello@mail.yourdomain.com",
  "to": "customer@example.com",
  "subject": "Welcome!",
  "status": "delivered",
  "provider": "ses",
  "sentAt": "2026-06-19T10:00:00.000Z",
  "deliveredAt": "2026-06-19T10:00:02.000Z",
  "createdAt": "2026-06-19T10:00:00.000Z"
}

List all domains added to your account.

// Response 200
{
  "domains": [
    {
      "id": "uuid",
      "domain": "mail.yourdomain.com",
      "status": "verified",
      "dnsProvider": "cloudflare",
      "createdAt": "2026-06-01T00:00:00.000Z"
    }
  ]
}

Add a new domain. Returns DNS records to publish for verification.

// Response 201
{
  "domain": { "id": "uuid", "domain": "mail.yourdomain.com", "status": "pending" },
  "dnsRecords": [
    { "type": "TXT", "name": "_amazonses.mail.yourdomain.com", "value": "abc123..." },
    { "type": "TXT", "name": "mail.yourdomain.com", "value": "v=spf1 include:amazonses.com ~all" },
    { "type": "CNAME", "name": "token1._domainkey.mail.yourdomain.com", "value": "token1.dkim.amazonses.com" }
  ],
  "isCloudflare": true,
  "message": "Add these DNS records to verify your domain"
}

Check whether SES has confirmed your DNS records. Call this after publishing DNS records.

// Response 200
{ "verified": true, "status": "verified", "message": "Domain verified successfully" }

// or if not yet verified:
{ "verified": false, "status": "pending", "message": "Domain not yet verified. Ensure DNS records are published and retry." }

Remove a domain from your account.

// Response 200
{ "message": "Domain removed" }

List all API keys (previews only — full key is never returned after creation).

// Response 200
{
  "keys": [
    {
      "id": "uuid",
      "name": "Production",
      "preview": "qle_****8f3a",
      "lastUsedAt": "2026-06-19T10:00:00.000Z",
      "createdAt": "2026-06-01T00:00:00.000Z"
    }
  ],
  "smtp": {
    "host": "smtp.quolle.com",
    "port": 587,
    "security": "STARTTLS",
    "note": "Use your API key as both username and password"
  }
}

Create a new API key. The full key is returned only in this response — store it immediately.

// Response 201
{
  "key": "qle_a1b2c3d4e5f6...",
  "id": "uuid",
  "name": "Production",
  "preview": "qle_****e5f6"
}

Revoke and delete an API key. Any requests using this key will immediately fail.

// Response 200
{ "message": "API key deleted" }

Get usage statistics for your account — current month and 6-month history.

// Response 200
{
  "current": {
    "sent": 842,
    "limit": 3000,
    "percentage": 28
  },
  "history": [
    { "month": "2026-01", "sent": 521 },
    { "month": "2026-02", "sent": 634 }
  ],
  "plan": { "name": "Starter", "monthlyLimit": 3000 }
}

List all configured webhook endpoints.

// Response 200
{
  "webhooks": [
    {
      "id": "uuid",
      "url": "https://yourapp.com/webhooks/email",
      "events": ["email.delivered", "email.bounced"],
      "createdAt": "2026-06-01T00:00:00.000Z"
    }
  ]
}

Create a webhook endpoint to receive delivery event notifications.

// Request
{ "url": "https://yourapp.com/webhooks/email", "events": ["email.delivered", "email.bounced"] }

// Response 201
{ "id": "uuid", "url": "https://yourapp.com/webhooks/email", "events": ["email.delivered", "email.bounced"] }

Delete a webhook endpoint.

// Response 200
{ "message": "Webhook deleted" }

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,
      "features": ["3,000 emails/mo", "API access", "SMTP access", "1 domain"]
    },
    {
      "id": "uuid",
      "name": "Growth",
      "monthlyLimit": 50000,
      "priceNaira": 15000,
      "features": ["50,000 emails/mo", "API access", "SMTP access", "5 domains", "Webhook support"]
    }
  ]
}

Initiate a plan upgrade. For paid plans, returns a Paystack payment URL. For the free Starter plan, switches immediately.

// Paid plan — Response 200
{ "authorizationUrl": "https://checkout.paystack.com/...", "reference": "ref_abc123" }

// Free plan — Response 200
{ "message": "Switched to Starter plan" }

Get current subscription status, plan details, and usage for the authenticated customer.

// Response 200
{
  "plan": { "id": "uuid", "name": "Growth", "monthlyLimit": 50000, "priceNaira": 15000 },
  "status": "active",
  "currentPeriodEnd": "2026-07-19T00:00:00.000Z",
  "usage": { "sent": 1240, "limit": 50000, "percentage": 2 }
}