Skip to main content

​
Introduction

The Sendook API provides programmatic access to send and receive emails at scale. Built on REST principles, the API uses standard HTTP response codes, authentication, and verbs.

​
Base URL

All API requests should be made to: 
https://api.sendook.com
For self-hosted installations, the API runs on port 8006 by default: 
http://localhost:8006

​
API Versioning

The Sendook API uses URL-based versioning. All endpoints are prefixed with the version number: 
https://api.sendook.com/v1/{resource}
The current stable version is v1.
All v1 endpoints require authentication via API key. See the Authentication guide for details.

​
Rate Limits

To ensure service reliability and fair usage, the Sendook API implements rate limiting:

​
Message Sending

  • 100 requests per hour per organization for message send operations
  • Rate limit applies to:
    • POST /v1/inboxes/{inboxId}/messages/send
    • POST /v1/inboxes/{inboxId}/messages/{messageId}/reply

​
Rate Limit Headers

Rate limit information is included in the response headers using the draft-7 standard: 
RateLimit-Limit: 100
RateLimit-Remaining: 95
RateLimit-Reset: 1677721600

​
Rate Limit Exceeded

When you exceed the rate limit, the API returns a 429 Too Many Requests response: 
{
  "error": "Too many requests, please try again later."
}
Rate limits are stored in Redis and reset on an hourly basis. Plan your integration accordingly to stay within limits.

​
Response Format

All API responses are returned as JSON with appropriate HTTP status codes.

​
Success Responses

Successful requests return the resource or an array of resources: 
{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Support Inbox",
  "email": "[email protected]",
  "organizationId": "507f191e810c19729de860ea",
  "createdAt": "2024-03-01T10:00:00.000Z",
  "updatedAt": "2024-03-01T10:00:00.000Z"
}

​
Error Responses

Errors return a JSON object with an error field describing the issue: 
{
  "error": "Inbox not found"
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
CodeDescription
200Success - Request completed successfully
201Created - Resource created successfully
400Bad Request - Invalid request parameters
401Unauthorized - Missing or invalid API key
404Not Found - Resource does not exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Something went wrong on the server

​
Request Format

All POST and PUT requests should include a Content-Type: application/json header.

​
Example Request

curl -X POST https://api.sendook.com/v1/inboxes \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support",
    "email": "[email protected]"
  }'

​
Pagination

Some endpoints that return lists support pagination through query parameters: 
GET /v1/inboxes?page=1&per=20
ParameterTypeDescription
pageintegerPage number (default: 1)
perintegerItems per page (default: 20)

​
Request Body Limits

The API accepts request bodies up to 20MB for most endpoints. This accommodates large email content and attachments.
Webhook endpoints have different body size limits. The Stripe and Resend webhook endpoints handle raw request bodies for signature verification.

​
CORS Support

The API supports Cross-Origin Resource Sharing (CORS) with credentials: 
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
This allows web applications to make direct API requests from the browser.

​
Health Check

You can check API health status using the health endpoint: 
curl https://api.sendook.com/health
Response: 
{
  "healthy": true,
  "environment": "production"
}

​
SDK Support

While you can use the REST API directly, Sendook provides official SDKs for easier integration:

Node.js SDK

Official TypeScript/JavaScript SDK

Python SDK

Coming soon - contributions welcome

​
Next Steps

Authentication

Learn how to authenticate your API requests

Inboxes

Create and manage email inboxes

Send Messages

Send emails via the API

Webhooks

Receive email events in real-time

Build docs developers (and LLMs) love

Get started for freeTalk to us