CloudMails REST API Reference | API Documentation

Authentication

All API requests require authentication using your API key. Include it in the Authorization header:

Authorization: Bearer your_api_key_here

Base URL

https://api.cloudmails.eu/v1

Sending Endpoints

POST /email/send

Send a single email

# Request Body { "to": "recipient@example.com", "from": "noreply@yourdomain.com", "subject": "Email Subject", "html": "

Email body HTML

", "text": "Email body plain text", "reply_to": "reply@yourdomain.com", "attachments": [ { "name": "invoice.pdf", "content": "base64_encoded_content" } ], "variables": { "user_name": "John" } } # Response (Success) { "success": true, "message_id": "msg_abc123xyz", "timestamp": 1716144000 }

POST /email/batch

Send batch emails with variable substitution

# Request Body { "from": "noreply@yourdomain.com", "subject": "Hello {{name}}", "html": "

Hi {{name}}, your order #{{order_id}} is ready.

", "recipients": [ {"to": "john@example.com", "name": "John", "order_id": "12345"}, {"to": "jane@example.com", "name": "Jane", "order_id": "12346"} ] }

Domain Management

POST /domains

Add a new sending domain

GET /domains

List all verified domains

POST /domains/{domain}/verify

Initiate domain verification

DELETE /domains/{domain}

Remove a domain

Webhooks

POST /webhooks

Create a webhook endpoint

# Webhook Event Types
- email.delivered
- email.bounced
- email.complained
- email.opened
- email.clicked

# Webhook Payload Example
{
  "event": "email.bounced",
  "timestamp": 1716144000,
  "data": {
    "message_id": "msg_abc123xyz",
    "bounce_type": "hard",
    "bounce_code": "5.1.1",
    "recipient": "invalid@example.com"
  }
}

IP Management

GET /ips

List all dedicated IPs

POST /ips/{ip}/warmup

Start warmup for an IP

GET /ips/{ip}/stats

Get IP statistics

Error Handling

# Standard Error Response
{
  "success": false,
  "error": {
    "code": "invalid_recipient",
    "message": "The recipient email address is invalid",
    "details": "Syntax check failed"
  }
}

# Error Codes
- invalid_recipient - Email address syntax invalid
- unauthorized - Invalid API key
- domain_not_verified - Sending domain not verified
- ip_not_warmed - IP warmup not complete
- rate_limited - Sending rate exceeded
- attachment_too_large - Attachment exceeds 10MB limit