API Reference

Base URL: https://api.keplars.com/api/v1

All endpoints require a Bearer token:

Authorization: Bearer $KEPLARS_API_KEY

API Key Types

Keplars has two types of API keys with different purposes and formats.

Regular API Keys

Used for sending emails programmatically. Created under Settings → API Keys in the dashboard.

Format:  kms_<workspaceId>.live_<secret>
Example: kms_019abc.live_a1b2c3d4e5f6...

These keys are tied to a specific email account in your workspace and can only call the email sending endpoints.

Admin API Keys

Used for the Marketing API - managing audiences, contacts, and reading campaign data. Created under Settings → Admin API Keys in the dashboard.

Format:  kms_<workspaceId>.adm_<secret>
Example: kms_019abc.adm_x9y8z7w6v5u4...

Admin keys are scoped - you choose which permissions to grant when creating the key.

Scope	Access
`contacts:read`	List and get contacts
`contacts:write`	Add, update, and delete contacts
`audiences:manage`	Create, list, get, and delete audiences

Which key do I need?

For sending emails → use a Regular API key. For audiences and contacts → use an Admin API key with the required scope. Marketing endpoints reject Regular keys with 403 FORBIDDEN.

Admin key limit

You can have a maximum of 5 Admin API keys per workspace. Regular keys have no limit.

Endpoints

Send Email

5 priority-tiered endpoints: instant, high, async, bulk, and schedule.

Webhooks

Email lifecycle events with HMAC-SHA256 signed payloads.

Audiences

Create and manage contact audiences for email campaigns.

Contacts

Add, update, list, and delete contacts within audiences.

Error Format

All errors return a consistent JSON shape:

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Field 'to' is required"
}

Status	Code	Meaning
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	Key type not allowed for this endpoint
403	`INSUFFICIENT_SCOPE`	Admin key missing required scope
400	`VALIDATION_ERROR`	Missing required field or invalid value
400	`INVALID_TEMPLATE`	`template_id` not found
429	`RATE_LIMITED`	Plan email quota reached
403	`PLAN_REQUIRED`	Feature requires LAUNCH plan or higher
500	`INTERNAL_ERROR`	Retry with exponential backoff