API Overview

Learn about the Sendook REST API, base URL, versioning, rate limits, and response formats

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": "[e-mail]",
  "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:

Code	Description
200	Success - Request completed successfully
201	Created - Resource created successfully
400	Bad Request - Invalid request parameters
401	Unauthorized - Missing or invalid API key
404	Not Found - Resource does not exist
429	Too Many Requests - Rate limit exceeded
500	Internal 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": "[e-mail]"
  }'

Pagination

Some endpoints that return lists support pagination through query parameters:

GET /v1/inboxes?page=1&per=20

Parameter	Type	Description
page	integer	Page number (default: 1)
per	integer	Items 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