API Reference

CubeMails API

Build email-powered applications with our REST API. Send transactional emails, validate addresses, manage templates, and query delivery data.

REST API v2 JSON Responses Bearer Auth

Authentication

Required

All API requests require an API key. Pass it via header:

HTTP Headers 
X-Server-API-Key: YOUR_API_KEY

# Or as Bearer token:
Authorization: Bearer YOUR_API_KEY
Where to find your key: Dashboard → Server → Credentials → Create API credential

Send Message

POST /api/v2/messages/send

Send a transactional email with subject, body, and recipient.

to string required Recipient email address
from string required Sender email address
subject string Email subject line
html_body string HTML email body
plain_body string Plain text email body
tag string Custom tag for filtering
cURL 
curl -X POST https://your-domain/api/v2/messages/send \
  -H "X-Server-API-Key: YOUR_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "to=user@example.com" \
  -d "from=hello@yourdomain.com" \
  -d "subject=Hello World" \
  -d "html_body=
Hi there!
"
Response 201 Created 
{
  "data": {
    "message_id": 12345,
    "messages": { ... }
  },
  "meta": {}
}

Send with Template

POST /api/v2/messages/send

Send using a pre-built template with dynamic variable substitution.

template string required Template slug (e.g. welcome-email)
template_variables[key] string Variables to interpolate (e.g. first_name)
cURL 
curl -X POST https://your-domain/api/v2/messages/send \
  -H "X-Server-API-Key: YOUR_KEY" \
  -d "to=alice@example.com" \
  -d "from=hello@yourdomain.com" \
  -d "template=welcome-email" \
  -d "template_variables[first_name]=Alice" \
  -d "template_variables[company]=Acme Inc"

List Messages

GET /api/v2/messages

Retrieve paginated list of messages sent through this server.

limit integer Max results (default 50, max 100)
page integer Page number
status string Filter by status

Get Message

GET /api/v2/messages/:id

Validate Email

POST /api/v2/validate/email

Check if an email address is valid, has MX records, and isn't from a disposable domain.

cURL 
curl -X POST https://your-domain/api/v2/validate/email \
  -H "X-Server-API-Key: YOUR_KEY" \
  -d "email=test@mailinator.com"
Response 200 OK 
{
  "data": {
    "email": "test@mailinator.com",
    "valid": false,
    "format_valid": true,
    "mx_found": true,
    "disposable": true,
    "normalized": "test@mailinator.com",
    "reason": "disposable_domain"
  }
}

Statistics

GET /api/v2/stats/global

Get daily email volume, bounce rates, and totals for up to 90 days.

days integer Number of days (default 30, max 90)

Webhook Events

CubeMails fires webhooks for these events:

MessageSent Delivered successfully
MessageDelayed Temporary delivery delay
MessageDeliveryFailed Permanent failure
MessageHeld Held for review
MessageBounced Bounce received
MessageLinkClicked Link clicked
MessageLoaded Email opened
DomainDNSError DNS misconfiguration

SMTP Relay

Use standard SMTP to send emails from any application:

SMTP Settings 
Host:     your-cubemails-instance.com
Port:     25 (or 587 for STARTTLS)
Username: your-smtp-credential-key
Password: (same as key)
Auth:     PLAIN
TLS:      STARTTLS

Error Handling

API v2 returns a standard error envelope:

Error Response 
{
  "error": {
    "code": "InvalidAPIKey",
    "message": "The provided API key is not valid."
  }
}
200 OK Request succeeded
201 Created Resource created
401 Unauthorized Invalid or missing API key
404 Not Found Resource not found
422 Validation Error Invalid request data
500 Server Error Internal server error

Legacy API v1

The v1 API is still supported for backward compatibility:

POST /api/v1/send/message Send a message
POST /api/v1/send/raw Send a raw RFC2822 message
GET /api/v1/messages/message Get message details
GET /api/v1/messages/deliveries Get delivery info