← Back to Console

API Usage — Prince Host Email API

This page shows quick examples for calling the Email API from PHP (cURL), JavaScript (browser & Node), and Python (requests). All requests require the x-api-key header unless your server is configured otherwise.

Overview

The API provides endpoints to send different types of transactional emails. Endpoints are:

POST /api/sendSignupCode
POST /api/sendResetCode
POST /api/sendResendCode
POST /api/sendDeleteCode
GET /api/health — health and provider status

Request body (JSON) for send endpoints:

{
  "username": "TestUser",
  "email": "user@example.com",
  "code": "123456"
}

Headers:

Content-Type: application/json
x-api-key: <YOUR_EMAIL_API_KEY>

PHP (cURL)

Example — send signup code

 'TestUser',
  'email' => 'user@example.com',
  'code' => '123456'
];

$ch = curl_init('http://localhost:3101/api/sendSignupCode');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Content-Type: application/json',
  'x-api-key: ' . $apiKey
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

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

echo "Status: " . ($info['http_code'] ?? 'n/a') . "\n";
echo $response . PHP_EOL;
?>

JavaScript (Browser fetch)

Browser example — using fetch()

const apiKey = 'YOUR_API_KEY';
const payload = { username: 'TestUser', email: 'user@example.com', code: '123456' };

fetch('/api/sendSignupCode', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': apiKey
  },
  body: JSON.stringify(payload)
})
.then(r => r.json())
.then(data => console.log('OK', data))
.catch(err => console.error('Error', err));

Node.js (server-side) — using node-fetch or built-in fetch

import fetch from 'node-fetch'; // or use global fetch in Node 18+

const apiKey = process.env.EMAIL_API_KEY;
const res = await fetch('http://localhost:3101/api/sendSignupCode', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': apiKey
  },
  body: JSON.stringify({ username: 'TestUser', email: 'user@example.com', code: '123456' })
});
const result = await res.json();
console.log(result);

Python (requests)

Example — send signup code

import requests

api_key = 'YOUR_API_KEY'
url = 'http://localhost:3101/api/sendSignupCode'
payload = { 'username': 'TestUser', 'email': 'user@example.com', 'code': '123456' }

resp = requests.post(url, json=payload, headers={ 'x-api-key': api_key })
print(resp.status_code)
print(resp.json())

Health Check

Call the health endpoint to inspect configured providers and connection state:

fetch('/api/health', { headers: { 'x-api-key': 'YOUR_API_KEY' } })
  .then(r => r.json())
  .then(data => console.log(data));

Example response shape:

{
  "config": { "appName": "Prince Host", "fromEmail": "support@princetechn.com" },
  "providers": {
    "brevo": { "enabled": true, "healthy": true, "consecutiveFailures": 0 },
    "resend": { "enabled": true, "healthy": true, "consecutiveFailures": 0 },
    "zoho": { "enabled": false, "healthy": false, "consecutiveFailures": 3 }
  }
}

Troubleshooting

403/401 responses usually indicate a missing or incorrect x-api-key.
500 responses indicate a server-side error — check server logs.
If health shows a provider disabled, ensure credentials are set in your server environment variables.

BY PRINCE M.