API Documentation
Everything you need to integrate Okural's email infrastructure into your application.
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
npm install @okural/sdkpip install okuralgo get github.com/okural/okural-gogem install okuralStep 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
/v3/emails/send—Send a single email1 token/v3/emails/batch—Send batch emails (up to 10,000 per request)1 token / email/v3/emails/{id}—Get email status and tracking data/v3/emails—List sent emails (paginated)/v3/emails/{id}/cancel—Cancel a scheduled emailEmail Verification
/v3/verify—Verify a single email address0.5 tokens/v3/verify/batch—Verify up to 50,000 addresses0.5 tokens / addr/v3/verify/batch/{id}—Get batch verification results/v3/verify/{email}/history—Verification history for an addressEmail Recovery
/v3/recovery/connect—Connect an email account (IMAP/POP3)/v3/recovery/sync—Trigger email sync from connected account2 tokens / email/v3/recovery/{account_id}/emails—List recovered emails/v3/recovery/{account_id}/emails/{id}—Get full email with attachments/v3/recovery/{account_id}—Disconnect an accountCustom IMAP
/v3/imap/accounts—Connect a custom IMAP account0.1 tokens / op/v3/imap/{account_id}/folders—List mailbox folders/v3/imap/{account_id}/messages—List messages (search, filter, paginate)/v3/imap/{account_id}/messages/{id}/move—Move a message between folders0.1 tokens/v3/imap/{account_id}/messages/{id}/flags—Set message flags (read, starred, etc.)0.1 tokens/v3/imap/{account_id}/messages/{id}—Get full message contentCampaigns
/v3/campaigns—Create a campaign1 token / recipient/v3/campaigns/{id}—Get campaign details and statistics/v3/campaigns/{id}/send—Launch a campaign/v3/campaigns—List all campaignsTemplates
/v3/templates—Create an email template/v3/templates—List all templates/v3/templates/{id}—Update a template/v3/templates/{id}/render—Preview template with sample dataAccount & Billing
/v3/account—Get account info/v3/account/usage—Token usage and remaining balance/v3/account/usage/breakdown—Usage 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.deliveredemail.openedemail.clickedemail.bouncedemail.complainedemail.unsubscribedverification.completedrecovery.syncedrecovery.email_foundExample 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/sdkFull TypeScript support. ESM and CJS builds.
Python
pip install okuralAsync support with asyncio. Python 3.8+.
Go
go get github.com/okural/okural-goIdiomatic Go client. Context-aware.
Ruby
gem install okuralRails integration available. Ruby 3.0+.
PHP
composer require okural/okural-phpLaravel and Symfony compatible. PHP 8.1+.
Java
com.okural:okural-java:2.4.0Spring 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.
| Plan | Rate Limit | Burst |
|---|---|---|
| Free | 50 req/s | 100 |
| Pay-as-you-go | 100 req/s | 200 |
| Starter | 200 req/s | 500 |
| Growth | 500 req/s | 1,000 |
| Business | 2,000 req/s | 5,000 |
| Enterprise | Custom | Custom |
Error Codes
Okural uses standard HTTP status codes. Every error response includes a machine-readable code and a human-readable message.
| Status | Name | Description |
|---|---|---|
| 200 | OK | Request succeeded |
| 201 | Created | Resource created successfully |
| 400 | Bad Request | Invalid parameters or malformed request body |
| 401 | Unauthorized | Invalid or missing API key |
| 403 | Forbidden | API key lacks required permissions |
| 404 | Not Found | Requested resource does not exist |
| 409 | Conflict | Duplicate request (idempotency key collision) |
| 422 | Unprocessable Entity | Validation failed — check the errors array |
| 429 | Too Many Requests | Rate limit exceeded — see Retry-After header |
| 500 | Internal Server Error | Something 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.