Email API

Before your first call

1. 1. Verify a domain.Add your domain in the dashboard and publish the DKIM, SPF and DMARC records it gives you. You may only send from a domain you own - that is what keeps everyone else's mail out of the spam folder as well as yours.
2. 2. Create an API key. It is shown once. Give it only the scopes it needs, and keep it on your server - a key in browser JavaScript is a key anyone can read.
3. 3. Send. Post to /api/email/v1/send with the key in an Authorization: Bearer header.

curl https://schedulekaro.com/api/email/v1/send \
  -H "Authorization: Bearer sk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": "customer@example.com",
    "subject": "Your order is on its way",
    "html": "<p>Thanks for your order.</p>"
  }'

How responses look

Every response is a JSON object with an ok field. On failure it carries a stable error.code as well as a sentence - write your code against the code, not the sentence, because the sentence is written for a human and may improve.

Scopes

• send — Send email and verification codes.
• read — Read message status, domains and suppressions, and check whether an address is deliverable.
• suppressions:write — Add and remove suppressed addresses.
• workflows:write — Put a contact into an automated workflow.

Rate limits

Calls are limited per key and per IP address. A RATE_LIMITED reply is safe to retry after a pause. Separately, each verified domain has a daily sending limit that rises as its reputation holds - a new domain starts small on purpose.

Sending

Every send is checked against the suppression list, your quota and the verified From domain before it reaches Amazon SES.

curl -X POST https://schedulekaro.com/api/email/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "hello@yourdomain.com",
  "to": "customer@example.com",
  "subject": "Your order is on its way",
  "html": "<p>Thanks for your order.</p>"
}'

{
  "ok": true,
  "data": {
    "id": "6f2f5f0c-2d1e-4f6f-9f1a-6f9a2d3b4c5d",
    "providerMessageId": "0100019...-000000"
  }
}

curl -X POST https://schedulekaro.com/api/email/v1/send-template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "template": "order-receipt",
  "from": "billing@yourdomain.com",
  "to": "customer@example.com",
  "data": {
    "first_name": "Asha",
    "total": "₹1,240"
  }
}'

{
  "ok": true,
  "data": {
    "id": "6f2f5f0c-2d1e-4f6f-9f1a-6f9a2d3b4c5d",
    "providerMessageId": "0100019...-000000",
    "template": "order-receipt",
    "templateVersion": 3
  }
}

curl -X POST https://schedulekaro.com/api/email/v1/send-batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "hello@yourdomain.com",
  "messages": [
    {
      "to": "a@example.com",
      "subject": "Hi",
      "html": "<p>Hi</p>"
    },
    {
      "to": "b@example.com",
      "template": "welcome",
      "data": {
        "first_name": "Ravi"
      }
    }
  ]
}'

{
  "ok": true,
  "data": {
    "accepted": 1,
    "rejected": 1,
    "results": [
      {
        "index": 0,
        "to": "a@example.com",
        "ok": true,
        "id": "6f2f5f0c-..."
      },
      {
        "index": 1,
        "to": "b@example.com",
        "ok": false,
        "error": {
          "code": "SUPPRESSED",
          "detail": "This address unsubscribed."
        }
      }
    ]
  }
}

Email verification

A one-time code to prove somebody owns the address they typed. One live code per address: asking again replaces the last one rather than leaving several valid.

curl -X POST https://schedulekaro.com/api/email/v1/verification/start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "hello@yourdomain.com",
  "email": "customer@example.com",
  "brand": "Kiran Tea Co."
}'

{
  "ok": true,
  "data": {
    "email": "customer@example.com",
    "expiresAt": "2026-09-01T09:25:00.000Z",
    "messageId": "6f2f5f0c-..."
  }
}

curl -X POST https://schedulekaro.com/api/email/v1/verification/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "customer@example.com",
  "code": "418302"
}'

{
  "ok": true,
  "data": {
    "email": "customer@example.com",
    "verified": true
  }
}

Messages

What happened to everything you sent.

curl -X GET https://schedulekaro.com/api/email/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "ok": true,
  "data": {
    "messages": [
      {
        "id": "6f2f5f0c-...",
        "to": "customer@example.com",
        "subject": "Your order is on its way",
        "status": "delivered",
        "createdAt": "2026-09-01T09:15:00.000Z"
      }
    ],
    "nextBefore": null
  }
}

curl -X GET https://schedulekaro.com/api/email/v1/messages/{id} \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "ok": true,
  "data": {
    "id": "6f2f5f0c-...",
    "status": "delivered",
    "openedAt": "2026-09-01T09:31:00.000Z",
    "events": [
      {
        "type": "send",
        "occurredAt": "2026-09-01T09:15:00.000Z"
      },
      {
        "type": "delivery",
        "occurredAt": "2026-09-01T09:15:04.000Z"
      },
      {
        "type": "open",
        "occurredAt": "2026-09-01T09:31:00.000Z"
      }
    ]
  }
}

Analytics

Delivery and engagement by day, read from a rollup that is recomputed every fifteen minutes. Cheap to poll, and the same numbers the dashboard shows.

curl -X GET https://schedulekaro.com/api/email/v1/stats \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "ok": true,
  "data": {
    "range": {
      "from": "2026-08-05",
      "to": "2026-09-03",
      "days": 30
    },
    "domain": null,
    "totals": {
      "sent": 12480,
      "accepted": 12475,
      "delivered": 12310,
      "opened": 5104,
      "clicked": 918,
      "bounced": 140,
      "complained": 21,
      "unsubscribed": 46,
      "failed": 5,
      "rejected": 0,
      "rates": {
        "delivery": 98.68,
        "open": 41.46,
        "click": 7.46,
        "bounce": 1.12,
        "complaint": 0.17,
        "unsubscribe": 0.37
      }
    },
    "daily": [
      {
        "day": "2026-09-03",
        "sent": 420,
        "accepted": 420,
        "delivered": 415,
        "opened": 190,
        "clicked": 33,
        "bounced": 5,
        "complained": 0,
        "unsubscribed": 2,
        "failed": 0,
        "rejected": 0,
        "rates": {
          "delivery": 98.81,
          "open": 45.78,
          "click": 7.95,
          "bounce": 1.19,
          "complaint": 0,
          "unsubscribe": 0.48
        }
      }
    ]
  }
}

Suppressions

Addresses that must not be emailed. Scope matters: "marketing" stops campaigns but still lets a receipt or a sign-in code through, which is what an unsubscribe usually means.

curl -X GET https://schedulekaro.com/api/email/v1/suppressions \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "ok": true,
  "data": {
    "suppressions": [
      {
        "email": "gone@example.com",
        "scope": "all",
        "reason": "bounce",
        "createdAt": "2026-08-30T11:02:00.000Z"
      }
    ]
  }
}

curl -X POST https://schedulekaro.com/api/email/v1/suppressions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "gone@example.com",
  "scope": "all"
}'

{
  "ok": true,
  "data": {
    "email": "gone@example.com",
    "scope": "all"
  }
}

curl -X DELETE https://schedulekaro.com/api/email/v1/suppressions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "asked-again@example.com"
}'

{
  "ok": true,
  "data": {
    "email": "asked-again@example.com",
    "removed": true
  }
}

Address validation

Check an address before you accept it. Catching a typo on a sign-up form saves an account that can never be confirmed, a support ticket, and a bounce against your sending domain.

curl -X POST https://schedulekaro.com/api/email/v1/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "priya@acme.in"
}'

{
  "ok": true,
  "data": {
    "email": "priya@acme.in",
    "result": "valid",
    "reason": "ok",
    "detail": "Nothing wrong with this address.",
    "deliverable": true
  }
}

Domains

The domains you may send from, and the state of their DNS.

curl -X GET https://schedulekaro.com/api/email/v1/domains \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "ok": true,
  "data": {
    "domains": [
      {
        "domain": "yourdomain.com",
        "verificationStatus": "verified",
        "dkimStatus": "verified",
        "spfStatus": "verified",
        "dmarcStatus": "pending",
        "healthScore": 85,
        "dailyLimit": 1000,
        "paused": false
      }
    ]
  }
}

Workflows

Automated sequences you design in the dashboard - a wait, an email, a condition - started by your own application.

curl -X GET https://schedulekaro.com/api/email/v1/workflows \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "ok": true,
  "data": {
    "workflows": [
      {
        "id": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
        "name": "Welcome series",
        "status": "active",
        "trigger": "api",
        "enrolled": 412,
        "completed": 297
      }
    ]
  }
}

curl -X POST https://schedulekaro.com/api/email/v1/workflows/{id}/enroll \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "asha@example.com"
}'

{
  "ok": true,
  "data": {
    "workflowId": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "email": "asha@example.com",
    "outcome": "enrolled"
  }
}