Skip to content
CloakMetric Docs

API Reference — CloakMetric REST API Documentation

The CloakMetric API allows you to programmatically manage aliases, send emails, and access analytics.

Authentication

Section titled “Authentication”

All requests require an API key in the Authorization header:

Terminal window
Authorization: Bearer cm_sk_your_api_key_here

Getting an API Key

Section titled “Getting an API Key”
  1. Go to Settings → API Keys
  2. Click Create API Key
  3. Name your key and select permissions
  4. Copy the key — it is shown only once!

Base URL

Section titled “Base URL”
https://www.cloakmetric.com/api/v1

Rate Limiting

Section titled “Rate Limiting”
  • Default — 1,000 requests per hour per key
  • Rate limit headers included in responses:
    • X-RateLimit-Limit
    • X-RateLimit-Remaining
    • X-RateLimit-Reset

Endpoints

Section titled “Endpoints”

Aliases

Section titled “Aliases”

List Aliases

Section titled “List Aliases”
GET /api/v1/aliases

Query Parameters:

ParameterTypeDescription
campaignIdstringFilter by campaign
isActivebooleanFilter by status
limitnumberMax results (1–100)
offsetnumberPagination offset

Response:

{
  "aliases": [
    {
      "id": "clx1234567890",
      "email": "hello@yourdomain.com",
      "isActive": true,
      "healthStatus": "healthy",
      "campaign": {
        "id": "clx0987654321",
        "name": "Outreach Q1"
      },
      "stats": {
        "emailsSent": 150,
        "repliesReceived": 12,
        "bounces": 2
      }
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 50,
    "offset": 0
  }
}

Create Alias

Section titled “Create Alias”
POST /api/v1/aliases

Body:

{
  "email": "custom-prefix@yourdomain.com",
  "campaignId": "clx0987654321"
}

Both fields are optional. If omitted, email is auto-generated and campaignId defaults to your default campaign.

Response:

{
  "id": "clx1234567890",
  "email": "custom-prefix@yourdomain.com",
  "isActive": true,
  "healthStatus": "healthy",
  "campaign": {
    "id": "clx0987654321",
    "name": "Outreach Q1"
  },
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Update Alias

Section titled “Update Alias”
PATCH /api/v1/aliases?id=clx1234567890

Body:

{
  "isActive": false,
  "campaignId": "clx0987654321"
}

Delete Alias

Section titled “Delete Alias”
DELETE /api/v1/aliases?id=clx1234567890

Campaigns

Section titled “Campaigns”

List Campaigns

Section titled “List Campaigns”
GET /api/v1/campaigns

Response:

{
  "campaigns": [
    {
      "id": "clx0987654321",
      "name": "Outreach Q1",
      "aliasCount": 12,
      "createdAt": "2024-01-10T08:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 50,
    "offset": 0
  }
}

Create Campaign

Section titled “Create Campaign”
POST /api/v1/campaigns

Body:

{
  "name": "Product Launch"
}

Update Campaign

Section titled “Update Campaign”
PATCH /api/v1/campaigns?id=clx0987654321

Body:

{
  "name": "Product Launch v2"
}

Delete Campaign

Section titled “Delete Campaign”
DELETE /api/v1/campaigns?id=clx0987654321

Emails

Section titled “Emails”

Send Email

Section titled “Send Email”
POST /api/v1/emails

Body:

{
  "aliasId": "clx1234567890",
  "to": "recipient@example.com",
  "subject": "Hello from CloakMetric",
  "text": "Plain text version of the email",
  "html": "<p>HTML version of the email</p>"
}

At least one of text or html is required.

Response:

{
  "id": "msg_abc123",
  "status": "sent",
  "aliasId": "clx1234567890",
  "to": "recipient@example.com",
  "subject": "Hello from CloakMetric",
  "sentAt": "2024-01-15T10:35:00.000Z"
}

Get Email Logs

Section titled “Get Email Logs”
GET /api/v1/emails

Query Parameters:

ParameterTypeDescription
aliasIdstringFilter by alias
directionstringINBOUND or OUTBOUND
limitnumberMax results (1–100)
offsetnumberPagination offset

Analytics

Section titled “Analytics”

Get Analytics Summary

Section titled “Get Analytics Summary”
GET /api/v1/analytics?period=7d

Periods: 7d, 14d, 30d

Response:

{
  "period": "7d",
  "overview": {
    "totalAliases": 25,
    "activeAliases": 20
  },
  "health": {
    "healthy": 18,
    "warning": 5,
    "risky": 2,
    "score": 82
  },
  "emails": {
    "totalSent": 5000,
    "totalReceived": 320,
    "totalBounces": 50
  },
  "rates": {
    "bounceRate": 1.0,
    "replyRate": 8.0,
    "complaintRate": 0.02
  }
}

Error Handling

Section titled “Error Handling”

All errors return a consistent JSON format:

{
  "error": "Error message describing what went wrong",
  "status": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Common Status Codes

Section titled “Common Status Codes”
CodeMeaning
200Success
201Created
400Bad Request — invalid parameters
401Unauthorized — missing or invalid API key
403Forbidden — plan limit reached
404Not Found
429Rate Limit Exceeded
500Server Error

Code Examples

Section titled “Code Examples”
const API_KEY = process.env.CLOAKMETRIC_API_KEY;
const BASE_URL = 'https://www.cloakmetric.com/api/v1';


// Create an alias
async function createAlias(campaignId) {
  const response = await fetch(`${BASE_URL}/aliases`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ campaignId }),
  });


  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }


  return response.json();
}


// Send an email
async function sendEmail(aliasId, to, subject, text) {
  const response = await fetch(`${BASE_URL}/emails`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ aliasId, to, subject, text }),
  });


  return response.json();
}


// Get analytics
async function getAnalytics(period = '7d') {
  const response = await fetch(`${BASE_URL}/analytics?period=${period}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
    },
  });


  return response.json();
}