API Documentation

Everything you need to integrate Okural's email infrastructure into your application.

https://api.okural.com/v3REST · JSON · TLS 1.3

Getting Started

Get up and running in under five minutes. Install the SDK, grab your API key from the dashboard, and send your first email.

Step 1 — Install the SDK

Node.jsnpm install @okural/sdk
Pythonpip install okural
Gogo get github.com/okural/okural-go
Rubygem install okural

Step 2 — Initialize the client

import { Okural } from '@okural/sdk';

const okural = new Okural({
  apiKey: process.env.OKURAL_API_KEY,
});

Step 3 — Send your first email

const email = await okural.emails.send({
  from: 'hello@yourapp.com',
  to: 'user@example.com',
  subject: 'Welcome aboard!',
  html: '<h1>Hello {{name}}</h1>',
  data: { name: 'Alex' },
});

console.log(email);
// {
//   id: "em_8f2k9xLm3nP",
//   status: "delivered",
//   tokens_used: 1,
//   created_at: "2025-11-20T09:14:32Z"
// }

Step 4 — Verify an address

const result = await okural.verify.check('user@example.com');

console.log(result);
// {
//   email: "user@example.com",
//   is_valid: true,
//   is_deliverable: true,
//   is_disposable: false,
//   risk_score: 0.12,
//   mx_found: true,
//   tokens_used: 0.5
// }

Authentication

Authenticate every request by passing your API key in the Authorization header.

curl https://api.okural.com/v3/account \
  -H "Authorization: Bearer ok_live_sk_7x8K2mN..."
ok_live_

Production keys. Emails are sent, tokens are consumed, webhooks fire. Use in production environments only.

ok_test_

Sandbox keys. No emails sent, no tokens consumed. API responses mirror production. Perfect for development and CI.

Keys are project-scoped. Configure read/write permissions per key from the dashboard → API Keys.

API Endpoints

Email Sending

POST/v3/emails/sendSend a single email1 token
POST/v3/emails/batchSend batch emails (up to 10,000 per request)1 token / email
GET/v3/emails/{id}Get email status and tracking data
GET/v3/emailsList sent emails (paginated)
DELETE/v3/emails/{id}/cancelCancel a scheduled email

Email Verification

POST/v3/verifyVerify a single email address0.5 tokens
POST/v3/verify/batchVerify up to 50,000 addresses0.5 tokens / addr
GET/v3/verify/batch/{id}Get batch verification results
GET/v3/verify/{email}/historyVerification history for an address

Email Recovery

POST/v3/recovery/connectConnect an email account (IMAP/POP3)
POST/v3/recovery/syncTrigger email sync from connected account2 tokens / email
GET/v3/recovery/{account_id}/emailsList recovered emails
GET/v3/recovery/{account_id}/emails/{id}Get full email with attachments
DELETE/v3/recovery/{account_id}Disconnect an account

Custom IMAP

POST/v3/imap/accountsConnect a custom IMAP account0.1 tokens / op
GET/v3/imap/{account_id}/foldersList mailbox folders
GET/v3/imap/{account_id}/messagesList messages (search, filter, paginate)
POST/v3/imap/{account_id}/messages/{id}/moveMove a message between folders0.1 tokens
PUT/v3/imap/{account_id}/messages/{id}/flagsSet message flags (read, starred, etc.)0.1 tokens
GET/v3/imap/{account_id}/messages/{id}Get full message content

Campaigns

POST/v3/campaignsCreate a campaign1 token / recipient
GET/v3/campaigns/{id}Get campaign details and statistics
POST/v3/campaigns/{id}/sendLaunch a campaign
GET/v3/campaignsList all campaigns

Templates

POST/v3/templatesCreate an email template
GET/v3/templatesList all templates
PUT/v3/templates/{id}Update a template
POST/v3/templates/{id}/renderPreview template with sample data

Account & Billing

GET/v3/accountGet account info
GET/v3/account/usageToken usage and remaining balance
GET/v3/account/usage/breakdownUsage breakdown by product (send, verify, IMAP, recovery)

Webhooks

Receive real-time notifications when events happen. Configure webhook endpoints from the dashboard or via the API.

email.delivered
email.opened
email.clicked
email.bounced
email.complained
email.unsubscribed
verification.completed
recovery.synced
recovery.email_found

Example payload

{
  "id": "evt_9xK2mN3pQ",
  "type": "email.delivered",
  "created_at": "2025-11-20T09:14:35Z",
  "data": {
    "email_id": "em_8f2k9xLm3nP",
    "to": "user@example.com",
    "subject": "Welcome aboard!",
    "delivered_at": "2025-11-20T09:14:34Z",
    "smtp_response": "250 OK"
  }
}

Retry Policy

Failed deliveries are retried 3 times with exponential backoff: 10 s, 60 s, 300 s. After 3 failures the event is marked as failed and available via the GET /v3/webhooks/events endpoint for manual replay.

Official SDKs

Node.js

npm install @okural/sdk

Full TypeScript support. ESM and CJS builds.

Python

pip install okural

Async support with asyncio. Python 3.8+.

Go

go get github.com/okural/okural-go

Idiomatic Go client. Context-aware.

Ruby

gem install okural

Rails integration available. Ruby 3.0+.

PHP

composer require okural/okural-php

Laravel and Symfony compatible. PHP 8.1+.

Java

com.okural:okural-java:2.4.0

Spring Boot starter included. Java 17+.

Rate Limits

Rate limits are applied per API key. Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

PlanRate LimitBurst
Free50 req/s100
Pay-as-you-go100 req/s200
Starter200 req/s500
Growth500 req/s1,000
Business2,000 req/s5,000
EnterpriseCustomCustom

Error Codes

Okural uses standard HTTP status codes. Every error response includes a machine-readable code and a human-readable message.

StatusNameDescription
200OKRequest succeeded
201CreatedResource created successfully
400Bad RequestInvalid parameters or malformed request body
401UnauthorizedInvalid or missing API key
403ForbiddenAPI key lacks required permissions
404Not FoundRequested resource does not exist
409ConflictDuplicate request (idempotency key collision)
422Unprocessable EntityValidation failed — check the errors array
429Too Many RequestsRate limit exceeded — see Retry-After header
500Internal Server ErrorSomething went wrong on our end — retry or contact support

Error response example

{
  "error": {
    "code": "validation_failed",
    "message": "The 'to' field must be a valid email address.",
    "param": "to",
    "doc_url": "https://docs.okural.com/errors/validation_failed"
  }
}

Ready to start building?

Create a free account and get 1,000 tokens to try every endpoint — no credit card required.