Send Emails via API (Transactional Email Guide)

Send transactional emails like OTPs, welcome messages, alerts, and custom emails using Voyant Email API with secure signature-based authentication.

Base URL: https://api.voyantnetworks.com
Endpoint:
• /v1/email/send

Authentication

All requests must be signed using your apiSecret . Send signature in header x-signature .

Required fields in body:

• projectId
• apiKey
• nonce (random alphanumeric exactly 10 characters)
• timestamp
• emailData (full object)

⚠️ Entire emailData must be included in signature calculation.
⚠️ Enum values are case-sensitive.

Field Values (Enums)

language → en | hi | es | fr | de | pt | ru | ja

button.type → filled | outlined | text

Signature Generation

1. POST request (application/json)
2. Include required fields + emailData
3. Create payload with ALL fields
4. Sort keys
5. HMAC-SHA256 using apiSecret
6. Send in x-signature header

import crypto from "node:crypto";

const payload = { nonce, projectId, apiKey, timestamp, emailData };

const stable = JSON.stringify(
  Object.keys(payload).sort().reduce((a,k)=>{a[k]=payload[k];return a;}, {})
);

const signature = crypto
  .createHmac("sha256", apiSecret)
  .update(stable)
  .digest("hex");

const payload = { nonce, projectId, apiKey, timestamp, emailData };

const stable = JSON.stringify(
  Object.keys(payload).sort().reduce((a,k)=>{a[k]=payload[k];return a;}, {})
);

const enc = new TextEncoder();

const key = await crypto.subtle.importKey(
  "raw",
  enc.encode(apiSecret),
  { name: "HMAC", hash: "SHA-256" },
  false,
  ["sign"]
);

const sig = await crypto.subtle.sign("HMAC", key, enc.encode(stable));

const signature = [...new Uint8Array(sig)]
  .map(b => b.toString(16).padStart(2, "0"))
  .join("");

import hmac, hashlib, json

payload = {
  "nonce": nonce,
  "projectId": projectId,
  "apiKey": apiKey,
  "timestamp": timestamp,
  "emailData": emailData
}

stable = json.dumps(payload, sort_keys=True)

signature = hmac.new(
  apiSecret.encode(),
  stable.encode(),
  hashlib.sha256
).hexdigest()

⚠️ emailData must be included in signature calculation.

Template Examples (Full)

All fields shown. Optional fields marked clearly.

{
  "to": "[email protected]",
  "language": "en", // optional → en | hi | es | fr | de | pt | ru | ja
  "detectLocation": true, // optional (default: false)
  "requestId": "req_123", // optional
  "fromType": "verify", // required → verify | noreply | support | alerts | billing | updates
  "replyTo": "[email protected]", // optional

  "templateName": "email_verification",
  "templateData": {
    "username": "John", // optional
    "otp": "123456", // optional (auto-generated if missing)
    "expiryMinutes": 10, // optional (default: 10)
    "deviceText": "Chrome on Windows" // optional
  }
}

{
  "to": "[email protected]",
  "language": "en", // optional
  "detectLocation": false, // optional
  "requestId": "req_456", // optional
  "fromType": "updates", // enum
  "replyTo": "[email protected]", // optional

  "templateName": "welcome",
  "templateData": {
    "username": "John", // optional
    "appName": "Voyant",

    "button": { // optional
      "type": "filled", // optional → filled | outlined | text
      "text": "Get Started",
      "url": "https://example.com",
      "color": "#4f46e5" // optional (default applied)
    }
  }
}

{
  "to": "[email protected]",
  "language": "en", // optional
  "detectLocation": true, // optional
  "requestId": "req_789", // optional
  "fromType": "support", // enum
  "replyTo": "[email protected]", // optional

  "templateName": "custom",
  "templateData": {
    "greeting": "Hello John",
    "title": "Important Update",
    "subtitle": "Please review this information",
    "message": "Your account settings have been updated successfully.",
    "subject": "Account Update",

    "button": { // optional
      "type": "outlined", // optional
      "text": "View Details",
      "url": "https://example.com",
      "color": "#22c55e" // optional
    }
  }
}

• nonce must be exactly 10 characters
• OTP auto-generated if not provided
• Rate limits apply
• Invalid signature → request fails