API Guide

Overview

The Kirim.Email SMTP API provides programmatic access to email sending, domain management, credentials, logs, and more. All API requests are made over HTTPS to https://smtp-app.kirim.email.

Authentication

All API requests require Basic Authentication with your API credentials. Your username serves as username, and the API key serves as password.

curl -X GET "https://smtp-app.kirim.email/api/domains" \
  -u "username:your-api-key"

Replace your-api-key with your actual API key from the dashboard.

Base URL

All API endpoints are relative to:

https://smtp-app.kirim.email

Domains

List Your Domains

Retrieve all domains associated with your account.

curl -X GET "https://smtp-app.kirim.email/api/domains" \
  -u "username:your-api-key"

Response:

{
  "success": true,
  "data": [
    {
      "id": "dm_xxxxx",
      "domain": "example.com",
      "status": "verified",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Create a Domain

Add a new domain to your account.

curl -X POST "https://smtp-app.kirim.email/api/domains" \
  -u "username:your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

Verify Domain DNS

After creating a domain, you need to verify your DNS records:

# Verify mandatory DNS records (SPF, DKIM, MX)
curl -X POST "https://smtp-app.kirim.email/api/domains/example.com/verify-mx" \
  -u "username:your-api-key"

# Setup and verify authentication domain (SPF, DKIM)
curl -X POST "https://smtp-app.kirim.email/api/domains/example.com/setup-auth" \
  -u "username:your-api-key"

# Setup and verify tracking domain (CNAME for click/open tracking)
curl -X POST "https://smtp-app.kirim.email/api/domains/example.com/setup-tracking" \
  -u "username:your-api-key"

Credentials

SMTP credentials allow you to send emails through specific domains.

List Credentials

curl -X GET "https://smtp-app.kirim.email/api/domains/example.com/credentials" \
  -u "username:your-api-key"

Create a Credential

curl -X POST "https://smtp-app.kirim.email/api/domains/example.com/credentials" \
  -u "username:your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Application"}'

Response:

{
  "success": true,
  "data": {
    "id": "cred_xxxxx",
    "name": "My Application",
    "username": "smtp_xxxxx",
    "password": "generated-password-here",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Important: Save the password immediately - it won’t be shown again.

Reset Credential Password

curl -X POST "https://smtp-app.kirim.email/api/domains/example.com/credentials/cred_xxxxx/reset-password" \
  -u "username:your-api-key"

Sending Email

Send with Direct Content

curl -X POST "https://smtp-app.kirim.email/api/domains/example.com/send" \
  -u "smtp_xxxxx:smtp-password" \
  -d "[email protected]" \
  -d "[email protected]" \
  -d "subject=Hello World" \
  -d "body=This is the email content"

Send with Attachments

curl -X POST "https://smtp-app.kirim.email/api/domains/example.com/send" \
  -u "smtp_xxxxx:smtp-password" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "subject=Hello with Attachment" \
  -F "body=Please see the attached file" \
  -F "attachment=@/path/to/file.pdf"

Send Using a Template

curl -X POST "https://smtp-app.kirim.email/api/domains/example.com/send-template" \
  -u "smtp_xxxxx:smtp-password" \
  -d "[email protected]" \
  -d "[email protected]" \
  -d "template=welcome-email" \
  -d "variables[name]=John Doe"

Email Validation

Validate email addresses before sending to reduce bounce rates.

Validate a Single Email

curl -X POST "https://smtp-app.kirim.email/api/validate/email" \
  -u "username:your-api-key" \
  -d "[email protected]"

Validate with Strict Mode

curl -X POST "https://smtp-app.kirim.email/api/validate/email/strict" \
  -u "username:your-api-key" \
  -d "[email protected]"

Validate Multiple Emails

curl -X POST "https://smtp-app.kirim.email/api/validate/email/batch" \
  -u "username:your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["[email protected]", "[email protected]", "[email protected]"]}'

Logs

Monitor your email sending activity.

Get Sending Logs

curl -X GET "https://smtp-app.kirim.email/api/domains/example.com/logs" \
  -u "username:your-api-key"

Get Logs for Specific Message

curl -X GET "https://smtp-app.kirim.email/api/domains/example.com/logs/message_xxxxx" \
  -u "username:your-api-key"

Stream Logs in Real-time

curl -X GET "https://smtp-app.kirim.email/api/domains/example.com/logs/stream" \
  -u "username:your-api-key"

Suppressions

Manage suppressed email addresses (bounces, unsubscribes, whitelist).

Get Suppressions

# Get all suppressions
curl -X GET "https://smtp-app.kirim.email/api/domains/example.com/suppressions" \
  -u "username:your-api-key"

# Get bounces only
curl -X GET "https://smtp-app.kirim.email/api/domains/example.com/suppressions/bounces" \
  -u "username:your-api-key"

# Get unsubscribes only
curl -X GET "https://smtp-app.kirim.email/api/domains/example.com/suppressions/unsubscribes" \
  -u "username:your-api-key"

Add to Whitelist

curl -X POST "https://smtp-app.kirim.email/api/domains/example.com/suppressions/whitelist" \
  -u "username:your-api-key" \
  -d "[email protected]"

Remove Suppressions

# Remove from unsubscribes
curl -X DELETE "https://smtp-app.kirim.email/api/domains/example.com/suppressions/unsubscribes" \
  -u "username:your-api-key" \
  -d "[email protected]"

Webhooks

Receive real-time notifications about email events.

Create a Webhook

curl -X POST "https://smtp-app.kirim.email/api/domains/example.com/webhooks" \
  -u "username:your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/kirimemail",
    "events": ["delivered", "bounced", "complained"]
  }'

Webhook Events

Available webhook events:

Event	Description
queued	Email queued for delivery
delivered	Email successfully delivered
bounced	Email was bounced
complained	Email marked as spam
clicked	Link in email was clicked
opened	Email was opened

Test a Webhook

curl -X POST "https://smtp-app.kirim.email/api/domains/example.com/webhooks/webhook_xxxxx/test" \
  -u "username:your-api-key"

Quota

Check your account’s sending limits and usage.

curl -X GET "https://smtp-app.kirim.email/api/quota" \
  -u "username:your-api-key"

Response:

{
  "success": true,
  "data": {
    "plan": "standard",
    "limit": 1000,
    "used": 450,
    "remaining": 550,
    "reset_at": "2024-01-31T23:59:59Z"
  }
}

Rate Limits

Plan	Limit
Standard	100 requests/minute
Enterprise	1000 requests/minute

When rate limited, the API returns a 429 Too Many Requests response.

Error Handling

The API uses standard HTTP status codes for responses.

Code	Meaning
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn’t exist
429	Too Many Requests - Rate limit exceeded
500	Server Error - Something went wrong

Error Response Format:

{
  "success": false,
  "error": {
    "code": "invalid_email",
    "message": "The provided email address is not valid"
  }
}

Code Examples

Python

import requests
from requests.auth import HTTPBasicAuth

api_key = "your-api-key"
base_url = "https://smtp-app.kirim.email"

# List domains
response = requests.get(
    f"{base_url}/api/domains",
    auth=HTTPBasicAuth("username", api_key)
)
print(response.json())

Node.js

const axios = require('axios');

const apiKey = 'your-api-key';
const baseUrl = 'https://smtp-app.kirim.email';

async function getDomains() {
  const response = await axios.get(`${baseUrl}/api/domains`, {
    auth: { username: 'username', password: apiKey }
  });
  console.log(response.data);
}

PHP

<?php

$apiKey = 'your-api-key';
$baseUrl = 'https://smtp-app.kirim.email';

$ch = curl_init("$baseUrl/api/domains");
curl_setopt($ch, CURLOPT_USERPWD, "username:$apiKey");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);