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. They also cover the Domains API for programmatic custom domain provisioning.

Programmatic Domain Provisioning

Use this flow to go from zero to sending email from your own domain entirely via the API - no dashboard required.

You need an Admin API key with both domains:manage and api-keys:create scopes.

Step 1 - Add your domain

POST /api/v1/public/domains/add-domain
Authorization: Bearer <admin-key>

{
  "domain": "mail.yourdomain.com",
  "region": "us-east-1"
}

Save the id from the response - you'll need it in every subsequent step.

{
  "data": {
    "id": "b1e2f3a4-...",
    "domain": "mail.yourdomain.com",
    "status": "pending",
    "dns_records": { ... }
  }
}

Add the DNS records returned in dns_records to your DNS provider (SPF, DKIM, DMARC, MAIL FROM).

Step 2 - Verify the domain

Poll this endpoint until verification_status is verified. DNS propagation typically takes 2–10 minutes.

GET /api/v1/public/domains/domain-status/{domainID}
Authorization: Bearer <admin-key>

{
  "data": {
    "verification_status": "verified"
  }
}

You can also trigger an active re-check:

POST /api/v1/public/domains/verify-domain/{domainID}
Authorization: Bearer <admin-key>

Step 3 - Create a sending API key

POST /api/v1/public/domains/api-keys/create
Authorization: Bearer <admin-key>

{
  "name": "My App Sending Key",
  "custom_domain_id": "b1e2f3a4-..."
}

{
  "data": {
    "secret_key": "kms_019abc.live_a1b2c3d4...",
    "api_key": { "id": "...", "name": "My App Sending Key" }
  }
}

Step 4 - Send email

Use the secret_key from Step 3 as a Regular API key on any send endpoint:

POST /api/v1/send-email/instant
Authorization: Bearer kms_019abc.live_a1b2c3d4...

{
  "from": "[email protected]",
  "to": [{ "email": "[email protected]" }],
  "subject": "Hello from my domain",
  "html": "<p>It works!</p>"
}

Endpoints

Sending Regions

Domain endpoints accept a region field that controls which Keplars sending infrastructure handles mail from your domain. Choose the region closest to your recipients for best deliverability.

Omitting region defaults to us-east-1. The region is fixed at creation time and cannot be changed after the domain is added.

Error Format

All errors return a consistent JSON shape:

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