Developer Documentation

import requests

response = requests.post(
    "https://api.octusrelay.com/v1/send",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "from": "hello@yourdomain.com",
        "to": "recipient@example.com",
        "subject": "Your first email via OctusRelay",
        "html": "<h1>It works!</h1>",
    },
)

print(response.json())
# {"id": "msg_a1b2c3d4e5f6", "status": "queued"}

const response = await fetch("https://api.octusrelay.com/v1/send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "hello@yourdomain.com",
    to: "recipient@example.com",
    subject: "Your first email via OctusRelay",
    html: "<h1>It works!</h1>",
  }),
});

const data = await response.json();
console.log(data);
// { id: "msg_a1b2c3d4e5f6", status: "queued" }

<?php

$ch = curl_init("https://api.octusrelay.com/v1/send");

curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer YOUR_API_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "from"    => "hello@yourdomain.com",
        "to"      => "recipient@example.com",
        "subject" => "Your first email via OctusRelay",
        "html"    => "<h1>It works!</h1>",
    ]),
]);

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

echo $response;
// {"id": "msg_a1b2c3d4e5f6", "status": "queued"}

# .env
MAIL_MAILER=smtp
MAIL_HOST=smtp.octusrelay.com
MAIL_PORT=587
MAIL_USERNAME=your-api-key
MAIL_PASSWORD=your-api-key
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=hello@yourdomain.com
MAIL_FROM_NAME="Your App"

# settings.py
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "smtp.octusrelay.com"
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = "your-api-key"
EMAIL_HOST_PASSWORD = "your-api-key"
DEFAULT_FROM_EMAIL = "hello@yourdomain.com"

// wp-config.php (with WP Mail SMTP plugin)
define('WPMS_ON', true);
define('WPMS_SMTP_HOST', 'smtp.octusrelay.com');
define('WPMS_SMTP_PORT', 587);
define('WPMS_SSL', 'tls');
define('WPMS_SMTP_AUTH', true);
define('WPMS_SMTP_USER', 'your-api-key');
define('WPMS_SMTP_PASS', 'your-api-key');
define('WPMS_MAIL_FROM', 'hello@yourdomain.com');
define('WPMS_MAIL_FROM_NAME', 'Your Site');

POST /v1/send

{
  "from": "newsletter@yourdomain.com",
  "from_name": "Weekly Digest",
  "to": [
    "alice@example.com",
    "bob@example.com",
    "charlie@example.com"
  ],
  "subject": "Your weekly digest",
  "html": "<h1>This week's highlights</h1>",
  "tags": ["marketing", "newsletter"]
}

// 200 OK - Single recipient
{
  "id": "msg_a1b2c3d4e5f6",
  "status": "queued",
  "created_at": "2026-02-27T10:30:00Z"
}

// 200 OK - Batch recipients
{
  "batch_id": "batch_x1y2z3",
  "total": 3,
  "queued": 3,
  "failed": 0
}

Type:  TXT
Host:  octusrelay._domainkey
Value: v=DKIM1; k=rsa; p=MIGfMA0GCSqGSI... (provided in dashboard)
TTL:   3600

Type:  TXT
Host:  _dmarc
Value: v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com; pct=100
TTL:   3600

# Start with p=none if you are testing, then move to quarantine or reject

# Verify the webhook signature in Python
import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode("utf-8"),
        payload.encode("utf-8"),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(
        f"sha256={expected}",
        signature
    )

// Install
// npm install @octusrelay/sdk

import { OctusRelay } from "@octusrelay/sdk";

const client = new OctusRelay({ apiKey: "or_live_your_api_key" });

const response = await client.send({
  from: "hello@yourdomain.com",
  to: "recipient@example.com",
  subject: "Hello from OctusRelay",
  html: "<p>Sent via the Node.js SDK.</p>",
});

console.log(response.id);     // msg_a1b2c3d4e5f6
console.log(response.status); // queued

// Install
// composer require octusrelay/sdk

use OctusRelay\Client;

$client = new Client("or_live_your_api_key");

$response = $client->send([
    "from"    => "hello@yourdomain.com",
    "to"      => "recipient@example.com",
    "subject" => "Hello from OctusRelay",
    "html"    => "<p>Sent via the PHP SDK.</p>",
]);

echo $response->id;     // msg_a1b2c3d4e5f6
echo $response->status; // queued

400 bad_request        # Malformed JSON or missing fields
401 unauthorized        # Invalid or missing API key
403 forbidden           # Key lacks permission for this domain
404 not_found           # Resource does not exist
422 validation_error    # Invalid field value
429 rate_limited        # Too many requests
500 internal_error      # Server error (retry safe)