Send Emails via API (Transactional Email Guide)

Authentication

All requests must be signed using your apiSecret . Send signature in request body as signature .

Required fields in body:

• • accountId (REQUIRED)
• • projectId
• • apiKey
• • nonce (random alphanumeric exactly 10 characters)
• • timestamp
• • signature
• • emailDataString (JSON string)

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

Request Flow (Pseudo)

1. emailData = { templateName, to, fromType, templateData, ... }

2. emailDataString = JSON.stringify(emailData)

3. payload = {
  accountId,
   apiKey,
   projectId,
   nonce,
   timestamp,
   emailDataString // json stringify
}

   nonce     → random 10 char string
   timestamp → milliseconds (Date.now())

4. stable = JSON.stringify(sorted(payload))
   ⚠️ keys MUST be sorted alphabetically

5. signature = HMAC_SHA256(stable, apiSecret)

6. body (x-www-form-urlencoded):
   add apiKey, projectId, nonce, timestamp, signature
   add emailDataString

7. POST → /v1/email/send

   headers:
   Content-Type: application/x-www-form-urlencoded

Official SDKs & Libraries

Use official SDKs for faster integration across platforms.

SDK Usage (Recommended)

Use account-level credentials with projectId.

//  nodejs usage below // read sdk readme from above links
const creds = {
  apiKey: "YOUR_API_KEY",
  accountId: "YOUR_ACCOUNT_ID", // 🔥 REQUIRED
  apiSecret: "YOUR_API_SECRET"
};

const email = new VoyantClient.EmailApiClient({
  credentials: creds,
  projectId: "YOUR_PROJECT_ID"
});

await email.sendVerificationEmail({
  to: "[email protected]",
  fromType: "verify",
  templateData: {
    username: "John"
  }
});

Field Values (Enums)

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 request body as signature

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",
  "detectLocation": true,
  "requestId": "req_123",
  "fromType": "verify",
  "replyTo": "[email protected]",

  "templateName": "email_verification",
  "templateData": {
    "username": "John",
    "otp": "123456",
    "expiryMinutes": 10,
    "deviceText": "Chrome on Windows"
  }
}

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

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

    "button": {
      "type": "filled",
      "text": "Get Started",
      "url": "https://example.com",
      "color": "#4f46e5"
    }
  }
}

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

  "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": {
      "type": "outlined",
      "text": "View Details",
      "url": "https://example.com",
      "color": "#22c55e"
    }
  }
}