Sending Transactional Emails

This endpoint queues a single, non-promotional email for immediate sending, ideal for time-sensitive notifications triggered by user actions, such as:

• Password resets
• Welcome messages
• Order confirmations

Endpoint

POST /email/send

Headers

Header	Value	Required
Authorization	Bearer <your-api-key>	✅ Yes
Content-Type	application/json	✅ Yes

Body Parameters

Parameter	Type	Required	Description
to	String	✅ Yes	The recipient's email address.
from	String	✅ Yes	The sender's email address. Must be a verified sender.
subject	String	✅ Yes	The subject line of the email.
html	String	❌ Optional	The HTML version of your email.
text	String	❌ Optional	The plain text version of your email.
templateId	String	❌ Optional	A custom template ID created on the platform.
templateVariables	Object	❌ Optional	A list of key-value pairs to override in the template.

tip

templateId can be found in the content section of your dashboard if you saved the template from the editor.

warning

Only one of html, text, or templateId should be provided.

warning

Ensure all keys in templateVariables exist in the template.

---

Examples

Sending Multiple Emails (HTML, Text, and Template)

JavaScript

const emails = [
  {
    type: "html",
    body: {
      to: "jane.html@example.com",
      from: "noreply@yourdomain.com",
      subject: "Welcome to BasicsEngage!",
      html: "<h1>Welcome!</h1><p>Thanks for joining our platform 🚀</p>"
    }
  },
  {
    type: "text",
    body: {
      to: "john.text@example.com",
      from: "noreply@yourdomain.com",
      subject: "Your Password Reset Request",
      text: "Password Reset: Follow this link to reset your password."
    }
  },
  {
    type: "template",
    body: {
      to: "sara.template@example.com",
      from: "noreply@yourdomain.com",
      subject: "Your Order Confirmation",
      templateId: "order-confirmation-123",
      templateVariables: {
        customer_name: "Sara Smith",
        order_id: "A12345",
        total: "$39.99"
      }
    }
  }
];

async function sendEmails() {
  for (const email of emails) {
    try {
      const response = await fetch("https://api.basicsengage.com/api/v0/dev/email/send", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "Authorization": "Bearer <your-api-key>"
        },
        body: JSON.stringify(email.body)
      });

      const data = await response.json();
      console.log(`✅ Sent ${email.type} email:`, data);
    } catch (error) {
      console.error(`❌ Failed to send ${email.type} email:`, error);
    }
  }
}

await sendEmails();

Python

import requests

url = "https://api.basicsengage.com/api/v0/dev/email/send"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <your-api-key>"
}

emails = [
    {
        "to": "jane.html@example.com",
        "from": "noreply@yourdomain.com",
        "subject": "Welcome to BasicsEngage!",
        "html": "<h1>Welcome!</h1><p>Thanks for joining our platform 🚀</p>"
    },
    {
        "to": "john.text@example.com",
        "from": "noreply@yourdomain.com",
        "subject": "Your Password Reset Request",
        "text": "Password Reset: Follow this link to reset your password."
    },
    {
        "to": "sara.template@example.com",
        "from": "noreply@yourdomain.com",
        "subject": "Your Order Confirmation",
        "templateId": "order-confirmation-123",
        "templateVariables": {
            "customer_name": "Sara Smith",
            "order_id": "A12345",
            "total": "$39.99"
        }
    }
]

for email in emails:
    response = requests.post(url, headers=headers, json=email)
    print(response.json())

C#

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var url = "https://api.basicsengage.com/api/v0/dev/email/send";
        var apiKey = "Bearer <your-api-key>";
        var emails = new[]
        {
            new {
                to = "jane.html@example.com",
                from = "noreply@yourdomain.com",
                subject = "Welcome to BasicsEngage!",
                html = "<h1>Welcome!</h1><p>Thanks for joining 🚀</p>"
            },
            new {
                to = "john.text@example.com",
                from = "noreply@yourdomain.com",
                subject = "Your Password Reset Request",
                text = "Password Reset: Follow this link to reset your password."
            },
            new {
                to = "sara.template@example.com",
                from = "noreply@yourdomain.com",
                subject = "Your Order Confirmation",
                templateId = "order-confirmation-123",
                templateVariables = new {
                    customer_name = "Sara Smith",
                    order_id = "A12345",
                    total = "$39.99"
                }
            }
        };

        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Authorization", apiKey);

            foreach (var email in emails)
            {
                var json = System.Text.Json.JsonSerializer.Serialize(email);
                var content = new StringContent(json, Encoding.UTF8, "application/json");
                var response = await client.PostAsync(url, content);
                var result = await response.Content.ReadAsStringAsync();
                Console.WriteLine(result);
            }
        }
    }
}

PHP

<?php
$url = "https://api.basicsengage.com/api/v0/dev/email/send";
$apiKey = "Bearer <your-api-key>";

$emails = [
  [
    "to" => "jane.html@example.com",
    "from" => "noreply@yourdomain.com",
    "subject" => "Welcome to BasicsEngage!",
    "html" => "<h1>Welcome!</h1><p>Thanks for joining our platform 🚀</p>"
  ],
  [
    "to" => "john.text@example.com",
    "from" => "noreply@yourdomain.com",
    "subject" => "Your Password Reset Request",
    "text" => "Password Reset: Follow this link to reset your password."
  ],
  [
    "to" => "sara.template@example.com",
    "from" => "noreply@yourdomain.com",
    "subject" => "Your Order Confirmation",
    "templateId" => "order-confirmation-123",
    "templateVariables" => [
      "customer_name" => "Sara Smith",
      "order_id" => "A12345",
      "total" => "$39.99"
    ]
  ]
];

foreach ($emails as $email) {
  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: $apiKey"
  ]);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($email));
  $response = curl_exec($ch);
  echo $response . "\n";
  curl_close($ch);
}
?>

cURL

# HTML Email
curl -X POST "https://api.basicsengage.com/api/v0/dev/email/send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "to": "jane.html@example.com",
    "from": "noreply@yourdomain.com",
    "subject": "Welcome to BasicsEngage!",
    "html": "<h1>Welcome!</h1><p>Thanks for joining 🚀</p>"
  }'

# TEXT Email
curl -X POST "https://api.basicsengage.com/api/v0/dev/email/send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "to": "john.text@example.com",
    "from": "noreply@yourdomain.com",
    "subject": "Your Password Reset Request",
    "text": "Password Reset: Follow this link to reset your password."
  }'

# TEMPLATE Email
curl -X POST "https://api.basicsengage.com/api/v0/dev/email/send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "to": "sara.template@example.com",
    "from": "noreply@yourdomain.com",
    "subject": "Your Order Confirmation",
    "templateId": "order-confirmation-123",
    "templateVariables": {
      "customer_name": "Sara Smith",
      "order_id": "A12345",
      "total": "$39.99"
    }
  }'

Responses

🟢 200

{
  "status": "success",
  "message": "Email queued successfully!",
  "data": {
    "messageId": "unique-queue-id",
    "dailyEmailCount": 12,
    "dailyEmailLimit": 100
  }
}

🔴 400

{
  "status": "error",
  "error": "Invalid email address format for field 'to'."
}

🔴 401

{
  "status": "error",
  "message": "Invalid API Key"
}

🔴 429

{
  "status": "error",
  "error": "Daily email quota exceeded. Please try again tomorrow."
}

🔴 500

{
  "status": "error",
  "message": "Internal server error. Please try again later."
}