SMTP API: REST Integration Guide

Base Configuration

🔑 API Authentication

All API requests require an API key passed in the Authorization header. Generate API keys in the CloudMails dashboard under Settings → API Keys.

                    
# Base URL for all API requests
BASE_URL = "https://api.cloudmails.eu/v1"

# Authentication header format
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
                    
                

Send Email Endpoint

POST /send

https://api.cloudmails.eu/v1/send

Request Parameters

Parameter	Type	Required	Description
to	string	Yes	Recipient email address
from	string	Yes	Sender email address (must be verified)
subject	string	Yes	Email subject line
html	string	Yes	HTML email body content
text	string	No	Plain text alternative body
reply_to	string	No	Reply-to address (defaults to from)
cc	string[]	No	Array of CC recipients
bcc	string[]	No	Array of BCC recipients
attachments	object[]	No	Array of attachment objects
custom_args	object	No	Custom metadata for webhooks

Code Examples

cURL

                    
curl -X POST "https://api.cloudmails.eu/v1/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "from": "sender@yourdomain.com",
    "subject": "Test Email",
    "html": "<html><body><h1>Hello</h1><p>This is a test email.</p></body></html>",
    "text": "Hello, this is a test email."
  }'
                    
                

Python

                    
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.cloudmails.eu/v1"

def send_email(to, subject, html_body, text_body=None):
    payload = {
        "to": to,
        "from": "sender@yourdomain.com",
        "subject": subject,
        "html": html_body
    }
    if text_body:
        payload["text"] = text_body

    response = requests.post(
        f"BASE_URL/send",
        json=payload,
        headers={"Authorization": f"Bearer API_KEY"}
    )
    return response.json()

# Send an email
result = send_email(
    to="recipient@example.com",
    subject="Hello from CloudMails",
    html_body="<h1>Hello</h1><p>This is a test.</p>"
)
print(result)
                    
                

JavaScript / Node.js

                    
const BASE_URL = 'https://api.cloudmails.eu/v1';
const API_KEY = 'YOUR_API_KEY';

async function sendEmail({ to, subject, html, text }) {
    const response = await fetch(`BASE_URL/send`, {
        method: 'POST',
        headers: {
            'Authorization': `Bearer API_KEY`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({ to, from: 'sender@yourdomain.com', subject, html, text })
    });

    return await response.json();
}

// Usage
sendEmail({
    to: 'recipient@example.com',
    subject: 'Hello from CloudMails',
    html: '<h1>Hello</h1><p>This is a test email.</p>'
}).then(console.log).catch(console.error);
                    
                

PHP

                    
$apiKey = 'YOUR_API_KEY';
$baseUrl = 'https://api.cloudmails.eu/v1';

function sendEmail($to, $subject, $html, $text = null) {
    $ch = curl_init("$baseUrl/send");
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $apiKey",
        "Content-Type: application/json"
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
        'to' => $to,
        'from' => 'sender@yourdomain.com',
        'subject' => $subject,
        'html' => $html,
        'text' => $text
    ]));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

    return json_decode($response, true);
}

$result = sendEmail(
    'recipient@example.com',
    'Hello from CloudMails',
    '<h1>Hello</h1><p>This is a test email.</p>'
);
print_r($result);
                    
                

Go

                    
package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

const API_KEY = "YOUR_API_KEY"
const BASE_URL = "https://api.cloudmails.eu/v1"

type EmailPayload struct {
    To      string `json:"to"`
    From    string `json:"from"`
    Subject string `json:"subject"`
    Html    string `json:"html"`
    Text    string `json:"text,omitempty"`
}

func sendEmail(to, subject, htmlBody, textBody string) (map[string]interface{}, error) {
    payload := EmailPayload{
        To:      to,
        From:    "sender@yourdomain.com",
        Subject: subject,
        Html:    htmlBody,
    }
    if textBody != "" {
        payload.Text = textBody
    }

    jsonData, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", BASE_URL+"/send", bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer "API_KEY)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    return result, nil
}
                    
                

Batch Send Endpoint

POST /send/batch

https://api.cloudmails.eu/v1/send/batch

Send multiple emails in a single API call. Useful for sending personalized campaigns to large lists.

                    
# Request body - array of email objects
{
  "messages": [
    {
      "to": "user1@example.com",
      "subject": "Hello {{name}}",
      "html": "<p>Hi {{name}},</p><p>Your order #{{order_id}} is ready.</p>"
    },
    {
      "to": "user2@example.com",
      "subject": "Hello {{name}}",
      "html": "<p>Hi {{name}},</p><p>Your order #{{order_id}} is ready.</p>"
    }
  ]
}
                    
                

✅ Batch Limits

Maximum 1000 messages per batch request. For larger campaigns, split into multiple requests. Batch sends are processed asynchronously and delivery can take up to 5 minutes for completion.

Email Status Endpoint

GET /emails/{message_id}

https://api.cloudmails.eu/v1/emails/{message_id}

Retrieve delivery status for a sent email. Message ID is returned in the send response.

Response Fields

Field	Type	Description
message_id	string	Unique identifier for this email
status	string	sent\|delivered\|bounced\|failed\|deferred
created_at	datetime	When the email was accepted
delivered_at	datetime	When delivery was confirmed (if applicable)
bounce_reason	string	Reason for bounce (if applicable)
opens	integer	Number of times email was opened
clicks	integer	Number of times links were clicked

Webhooks

Configure webhooks to receive real-time notifications about email events.

Webhook Events

delivered - Email accepted by recipient server
bounced - Email rejected by recipient server
opened - Email was opened by recipient
clicked - Link in email was clicked
unsubscribed - Recipient clicked unsubscribe
complained - Recipient marked as spam

                    
// Example webhook payload for "delivered" event
{
  "event": "delivered",
  "message_id": "msg_abc123xyz",
  "timestamp": "2026-05-19T14:30:00Z",
  "recipient": "recipient@example.com",
  "custom_args": { "user_id": "12345" }
}
                    
                

🔗 Webhook Configuration

Webhooks are configured in the CloudMails dashboard under Settings → Webhooks. You'll need to provide an HTTPS endpoint URL that accepts POST requests. CloudMails will send a test ping to verify connectivity before activating.

Error Codes

Code	Error	Description
400	Invalid Request	Missing required fields or malformed JSON
401	Unauthorized	Invalid or missing API key
403	Forbidden	Sender address not verified
429	Rate Limited	Too many requests, slow down
500	Server Error	CloudMails internal error

SDK Libraries

Official SDK libraries are available for quick integration:

Python: pip install cloudmails
Node.js: npm install cloudmails-sdk
PHP: composer require cloudmails/sdk
Go: go get github.com/cloudmails/cloudmails-go
Ruby: gem install cloudmails

Get API Access →

SMTP API Documentation