Introduction

The KiriMel API allows you to programmatically manage your email marketing operations, including campaigns, subscribers, lists, automations, and more. You can use the API to build custom integrations, automate workflows, and extend KiriMel's functionality to meet your specific needs.

Client Libraries

By default, the KiriMel API documentation demonstrates using curl to interact with the API over HTTP. You can also use our official SDKs or any HTTP client library.

Authentication

The KiriMel API uses API keys to authenticate requests. You can view and manage your API keys in the KiriMel Dashboard.

Authentication Methods

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

curl https://kirimel.com/api/lists \
  -H "X-API-Key: sk_test_YOUR_API_KEY"

curl https://kirimel.com/api/lists \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"

Test Mode vs Live Mode

API keys have prefixes that indicate their mode:

• sk_test_ - Test mode keys (for development and testing)
• sk_live_ - Live mode keys (for production use)

Use test mode keys to build and test your integration without affecting your live data or incurring costs.

Sample Test API Key

A sample test API key is included in all the examples throughout this documentation, so you can test any example right away. Do not submit any personally identifiable information in requests made with this key.

To test requests using your account, replace the sample API key with your actual API key or sign in to your account.

SDK Quick Start

Get up and running quickly with our official SDKs. Each SDK provides type-safe interfaces to all KiriMel API v2 endpoints.

composer require hualiglobal/kirimel-php-sdk

<?php
require 'vendor/autoload.php';

use KiriMel\Client;

// Initialize the client
$client = new Client([
    'api_key' => 'sk_test_xxx'
]);

// List campaigns
$campaigns = $client->campaigns->list(['limit' => 20]);

// Create a campaign
$campaign = $client->campaigns->create([
    'name' => 'Welcome Email',
    'subject' => 'Welcome to KiriMel!',
    'list_id' => 123,
    'template_id' => 456
]);

// Get campaign statistics
$stats = $client->campaigns->stats($campaign['id']);
echo "Opens: {$stats['opens']}, Clicks: {$stats['clicks']}";
?>

pip install kirimel-python

import kirimel

# Initialize the client
client = kirimel.KiriMel(
    api_key='sk_test_xxx'
)

# List campaigns
campaigns = client.campaigns.list(limit=20)

# Create a campaign
campaign = client.campaigns.create({
    'name': 'Welcome Email',
    'subject': 'Welcome to KiriMel!',
    'list_id': 123,
    'template_id': 456
})

# Get campaign statistics
stats = client.campaigns.stats(campaign['id'])
print(f"Opens: {stats['opens']}, Clicks: {stats['clicks']}")

npm install @hualiglobal/kirimel-node-sdk

const { Client } = require('@hualiglobal/kirimel-node-sdk');

// Initialize the client
const client = new Client({
    apiKey: 'sk_test_xxx'
});

// List campaigns
const campaigns = await client.campaigns.list({ limit: 20 });

// Create a campaign
const campaign = await client.campaigns.create({
    name: 'Welcome Email',
    subject: 'Welcome to KiriMel!',
    list_id: 123,
    template_id: 456
});

// Get campaign statistics
const stats = await client.campaigns.stats(campaign.id);
console.log(`Opens: ${stats.opens}, Clicks: ${stats.clicks}`);

SDK Features

All SDKs include the following features:

• Full API Coverage - Access to all API v2 endpoints
• Type-Safe - Full type hints (PHP), type annotations (Python), TypeScript definitions (Node.js)
• Error Handling - Specific exceptions for auth, rate limiting, and validation errors
• Retry Logic - Automatic retry with exponential backoff
• 9 Resource Clients - Campaigns, Subscribers, Lists, Segments, Templates, Forms, Conversions, Landing Pages, Workflows

Authentication

All SDKs support two authentication methods:

• API Key - Pass api_key parameter when initializing the client
• Environment Variable - Set KIRIMEL_API_KEY environment variable

# Method 1: API Key (recommended)
client = new Client(['api_key' => 'sk_test_xxx'])

# Method 2: Environment variable
export KIRIMEL_API_KEY=sk_test_xxx
client = new Client()

Errors

KiriMel uses conventional HTTP response codes to indicate the success or failure of an API request.

In general:

• Codes in the 2xx range indicate success.
• Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a campaign failed to send, etc.).
• Codes in the 5xx range indicate an error with KiriMel's servers (these are rare).

HTTP Status Code Summary

Error Response Format

All error responses follow this format:

{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "email": ["The email field is required."],
        "list_id": ["The specified list does not exist."]
    }
}

Error Types

Rate Limiting

API requests are rate limited based on your subscription plan to ensure fair usage and system stability.

Rate Limit Tiers

Rate Limit Headers

Every API response includes headers indicating your rate limit status:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1740544800

Handling Rate Limits

When you exceed your rate limit, the API returns a 429 Too Many Requests status code. We recommend implementing exponential backoff:

// Exponential backoff example
async function makeRequestWithBackoff(url, options, maxRetries = 3) {
    for (let i = 0; i < maxRetries; i++) {
        const response = await fetch(url, options);

        if (response.status !== 429) return response;

        // Exponential backoff: 2^i seconds
        const backoffTime = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, backoffTime));
    }
}

Pagination

List endpoints in the KiriMel API support pagination to handle large result sets efficiently.

Paginated Response Format

{
    "success": true,
    "message": "Lists retrieved successfully",
    "data": {
        "items": [...],
        "pagination": {
            "current_page": 1,
            "per_page": 25,
            "total": 100,
            "total_pages": 4,
            "has_next_page": true,
            "has_prev_page": false
        }
    }
}

Pagination Parameters

Filtering & Sorting

Many list endpoints support filtering and sorting to help you find the data you need.

Common Parameters

Example

# Get sent campaigns sorted by created date
curl "https://kirimel.com/api/campaigns?status=sent&sort_by=created_at&sort_order=desc" \
  -H "X-API-Key: sk_test_YOUR_API_KEY"

Core API Resources

The following endpoints provide access to KiriMel's core email marketing functionality.

Lists

Manage your mailing lists and audiences.

curl https://kirimel.com/api/lists \
  -H "X-API-Key: sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Newsletter",
    "description": "Weekly updates and offers",
    "from_name": "My Company",
    "from_email": "noreply@example.com"
  }'

$apiKey = 'sk_test_YOUR_API_KEY';
$data = [
    'name' => 'My Newsletter',
    'description' => 'Weekly updates and offers',
    'from_name' => 'My Company',
    'from_email' => 'noreply@example.com'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://kirimel.com/api/lists');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($ch));
$response = curl_exec($ch);

import requests

api_key = 'sk_test_YOUR_API_KEY'
url = 'https://kirimel.com/api/lists'

data = {
    'name': 'My Newsletter',
    'description': 'Weekly updates and offers',
    'from_name': 'My Company',
    'from_email': 'noreply@example.com'
}

response = requests.post(url, json=data, headers={'X-API-Key': api_key})
print(response.json())

const axios = require('axios');

const apiKey = 'sk_test_YOUR_API_KEY';

const response = await axios.post('https://kirimel.com/api/lists', {
    name: 'My Newsletter',
    description: 'Weekly updates and offers',
    from_name: 'My Company',
    from_email: 'noreply@example.com'
}, {
    headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
    }
});

console.log(response.data);

{
    "success": true,
    "message": "List created successfully",
    "data": {
        "id": 123,
        "name": "My Newsletter",
        "description": "Weekly updates and offers",
        "subscriber_count": 0,
        "created_at": "2026-03-01T10:00:00Z"
    }
}

Subscribers

Manage subscribers across all your lists.

# Add subscriber with double opt-in (default)
curl https://kirimel.com/api/subscribers \
  -H "X-API-Key: sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "list_id": 123,
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890"
  }'

# Add subscriber directly as subscribed (skip confirmation)
curl https://kirimel.com/api/subscribers \
  -H "X-API-Key: sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "list_id": 123,
    "email": "user@example.com",
    "skip_confirmation": true
  }'

$data = [
    'list_id' => 123,
    'email' => 'user@example.com',
    'first_name' => 'John',
    'last_name' => 'Doe',
    'skip_confirmation' => true  // Set to true to skip double opt-in
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://kirimel.com/api/subscribers');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey,
    'Content-Type: application/json'
]);
$response = curl_exec($ch);

const axios = require('axios');

// Add subscriber directly as subscribed
const response = await axios.post('https://kirimel.com/api/subscribers', {
  list_id: 123,
  email: 'user@example.com',
  first_name: 'John',
  last_name: 'Doe',
  skip_confirmation: true  // Skip double opt-in, add as subscribed
}, {
  headers: {
    'X-API-Key': 'sk_test_YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

Campaigns

Create, manage, and send email campaigns.

curl https://kirimel.com/api/campaigns \
  -H "X-API-Key: sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Sale",
    "subject_line": "Don'\''t Miss Out! 50% Off Everything",
    "preview_text": "Our biggest sale of the year is here",
    "content_html": "
Summer Sale!
50% off everything
",
    "from_name": "My Brand",
    "reply_to_email": "noreply@example.com",
    "list_id": 123
  }'

$data = [
    'name' => 'Summer Sale',
    'subject_line' => "Don't Miss Out! 50% Off Everything",
    'content_html' => '
Summer Sale!
50% off everything
',
    'from_name' => 'My Brand',
    'reply_to_email' => 'noreply@example.com',
    'list_id' => 123
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://kirimel.com/api/campaigns');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey,
    'Content-Type: application/json'
]);
$response = curl_exec($ch);

Automations

Manage email automation workflows.

Advanced Features

Advanced API endpoints for segmentation, forms, conversions, CRM, and behavioral tracking.

Segments

Manage dynamic subscriber segments with RFM analysis and custom conditions.

Forms & Popups

Manage forms and collect submissions from your website.

Conversions

Track revenue and conversions from email campaigns.

Lead Scoring & CRM

Access subscriber profiles, activity timelines, and lead scoring data.

Behavioral Tracking

Track visitor behavior on your website for targeted email automation.

Transactional Email

Send individual transactional emails and manage SES settings.

curl https://kirimel.com/api/email/send \
  -H "X-API-Key: sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Welcome to Our Service!",
    "html": "
Welcome!
Thank you for signing up.
",
    "text": "Welcome! Thank you for signing up.",
    "from_name": "My App",
    "reply_to": "support@example.com"
  }'

$data = [
    'to' => 'recipient@example.com',
    'subject' => 'Welcome to Our Service!',
    'html' => '
Welcome!
Thank you for signing up.
',
    'text' => 'Welcome! Thank you for signing up.',
    'from_name' => 'My App',
    'reply_to' => 'support@example.com'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://kirimel.com/api/email/send');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey,
    'Content-Type: application/json'
]);
$response = curl_exec($ch);

Webhooks

Configure webhooks to receive real-time notifications about events in your KiriMel account.

Supported Events

Webhook Payload Format

All webhook payloads follow this structure:

{
    "event": "campaign.opened",
    "data": {
        "campaign_id": 123,
        "subscriber_id": 456,
        "email": "user@example.com",
        "opened_at": "2026-03-01T10:30:00Z",
        "ip_address": "192.168.1.1",
        "user_agent": "Mozilla/5.0..."
    },
    "timestamp": "2026-03-01T10:30:00Z"
}

Signature Verification

Webhook payloads include a signature header for verification:

X-KiriMel-Signature: sha256=abc123def456...

Verify the signature using your webhook secret:

$signature = $_SERVER['HTTP_KIRIMEL_SIGNATURE'];
$payload = file_get_contents('php://input');
$expectedSignature = hash_hmac('sha256', $payload, $webhookSecret);

if (hash_equals($expectedSignature, $signature)) {
    // Signature is valid, process webhook
} else {
    // Invalid signature, reject request
}

Retry Policy

If your webhook endpoint returns a non-2xx status code or times out, KiriMel will retry delivery with exponential backoff:

• Retry 1: 1 minute after failure
• Retry 2: 5 minutes after failure
• Retry 3: 30 minutes after failure
• Retry 4: 2 hours after failure

After 4 failed attempts, the webhook is marked as failed and won't be retried.