Skip to main content

​
Overview

The Sendook API uses API keys for authentication. API keys are organization-scoped tokens that authenticate requests to the v1 API endpoints.
All API requests must include an Authorization header with your API key as a Bearer token.

​
Authentication Methods

Sendook supports two authentication strategies: Used for all v1 API endpoints. API keys are associated with your organization and provide full access to organization resources.

​
2. Bearer Token Authentication

Used for non-API endpoints (like /auth, /organizations). These are user-scoped access tokens obtained through the authentication flow.
This guide focuses on API key authentication for the v1 API. For dashboard and user authentication, see the Dashboard Guide.

​
Getting Your API Key

You can create and manage API keys through the Sendook dashboard or via the API itself.

​
Via Dashboard

  1. Log in to your Sendook dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Give your key a descriptive name (e.g., “Production”, “Staging”)
  5. Copy and securely store your API key
API keys are shown only once upon creation. Store them securely and never commit them to version control.

​
Via API

You can also manage API keys programmatically: 
curl -X POST https://api.sendook.com/v1/api_keys \
  -H "Authorization: Bearer your_existing_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key"
  }'
Response: 
{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Production Key",
  "key": "sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "organizationId": "507f191e810c19729de860ea",
  "active": true,
  "createdAt": "2024-03-01T10:00:00.000Z",
  "updatedAt": "2024-03-01T10:00:00.000Z"
}

​
Making Authenticated Requests

Include your API key in the Authorization header as a Bearer token: 
curl https://api.sendook.com/v1/inboxes \
  -H "Authorization: Bearer your_api_key"

​
Request Flow

When you make an authenticated request:
  1. Your API key is extracted from the Authorization header
  2. Sendook validates the key using the api_key Passport strategy
  3. The associated organization is loaded and attached to the request
  4. Your request proceeds with organization-scoped access
From the source code at ~/workspace/source/api/routes/v1/index.ts:13-18: 
router.use(
  passport.authenticate("api_key", { session: false }),
  (req, res, next) => {
    req.organization = req.user as HydratedDocument<Organization>;
    next();
  }
);

​
API Key Validation

API keys are validated using Passport.js with a custom bearer strategy. Here’s how it works under the hood:
1

Extract Token

The API key is extracted from the Authorization: Bearer <token> header
2

Database Lookup

Sendook queries the database for an API key matching the provided token
3

Organization Validation

The organization associated with the API key is verified and loaded
4

Request Authorization

The organization object is attached to the request for authorization checks
From ~/workspace/source/api/controllers/PassportController.ts:29-48: 
export const passportApiKeyStrategy = new BearerStrategy(
  async (token, done) => {
    try {
      const apiKey = await getApiKeyByKey(token);
      if (!apiKey) {
        return done(null, false);
      }
      const organization = await getOrganizationById(
        apiKey.organizationId.toString()
      );
      if (!organization) {
        return done(null, false);
      }
      return done(null, {
        ...(organization?.toJSON()),
        apiKey,
      });
    } catch (err) {
      return done(err, null);
    }
  }
);

​
Managing API Keys

​
List API Keys

Retrieve all API keys for your organization: 
curl https://api.sendook.com/v1/api_keys \
  -H "Authorization: Bearer your_api_key"

​
Get Specific API Key

curl https://api.sendook.com/v1/api_keys/{apiKeyId} \
  -H "Authorization: Bearer your_api_key"

​
Delete API Key

Revoke an API key when it’s no longer needed: 
curl -X DELETE https://api.sendook.com/v1/api_keys/{apiKeyId} \
  -H "Authorization: Bearer your_api_key"
Deleting an API key immediately revokes access. Any requests using that key will fail with a 401 Unauthorized error.

​
Authentication Errors

​
401 Unauthorized

Returned when authentication fails: 
{
  "error": "Unauthorized"
}
Common causes:
  • Missing Authorization header
  • Invalid or expired API key
  • API key format is incorrect
  • API key has been deleted or deactivated

​
Example Error Response

curl https://api.sendook.com/v1/inboxes
# Missing Authorization header
Response: 
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "Unauthorized"
}

​
Security Best Practices

  • Never commit API keys to version control
  • Use environment variables or secret management services
  • Rotate keys periodically for enhanced security
Create different API keys for development, staging, and production environments. This allows you to:
  • Isolate environments
  • Revoke keys without affecting other environments
  • Track usage per environment
  • Only share API keys with team members who need them
  • Use service-specific keys when possible
  • Delete unused or compromised keys immediately
  • Regularly review API logs in your dashboard
  • Set up alerts for unusual activity
  • Track which keys are being used and where

​
Environment Variables

Store your API key as an environment variable: 
SENDOOK_API_KEY=sk_live_your_api_key_here
For self-hosted installations, Bun automatically loads .env files. No additional dotenv package is needed.

​
Rate Limiting and Authentication

Authenticated requests are subject to rate limiting. See the API Overview for details on rate limits. Rate limits are tracked per organization, not per API key. Multiple API keys for the same organization share the same rate limit pool.

​
Testing Authentication

Test your API key with a simple health check: 
curl https://api.sendook.com/v1/api_keys \
  -H "Authorization: Bearer your_api_key"
If authentication succeeds, you’ll receive a list of your API keys. If it fails, you’ll receive a 401 Unauthorized response.

​
Next Steps

Create an Inbox

Start by creating your first inbox

Send a Message

Send your first email via the API

Set Up Webhooks

Receive incoming email notifications

Node.js SDK

Use the official SDK for easier integration

Build docs developers (and LLMs) love

Get started for freeTalk to us