Send Email

API reference for sending transactional emails.

Send a transactional email through the PlatformXe multi-provider fallback chain.

Endpoint

POST /api/v1/messaging/email/send

Scope: messaging:send

Request body

Field	Type	Required	Description
to	Array<{ email: string, name?: string }>	Yes	Recipients (max 50)
subject	string	Yes	Email subject line
html	string	Yes	Pre-rendered HTML body
replyTo	string	No	Reply-to email address
attachments	Array<{ filename: string, content: string, contentType: string }>	No	Base64-encoded attachments

Response

{
  "success": true,
  "data": {
    "messageId": "msg_abc123def456",
    "status": "queued"
  }
}

Field	Type	Description
messageId	string	Unique message identifier for tracking
status	string	queued (accepted for delivery) or sent (delivered synchronously)

Examples

curl

curl -X POST https://api.platformxe.com/api/v1/messaging/email/send \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -H "x-idempotency-key: order-confirm-12345" \
  -d '{
    "to": [
      { "email": "jane@example.com", "name": "Jane Doe" }
    ],
    "subject": "Order #12345 Confirmed",
    "html": "<h1>Order Confirmed</h1><p>Your order has been placed successfully.</p>",
    "replyTo": "support@yourapp.com"
  }'

SDK

import { PlatformXe } from '@caldera/platformxe-sdk';

const px = new PlatformXe({ apiKey: 'pxk_live_your_api_key_here' });

const result = await px.email.send({
  to: [{ email: 'jane@example.com', name: 'Jane Doe' }],
  subject: 'Order #12345 Confirmed',
  html: '<h1>Order Confirmed</h1><p>Your order has been placed successfully.</p>',
  replyTo: 'support@yourapp.com',
});

console.log(result.data.messageId);
// "msg_abc123def456"

With attachments

import { readFileSync } from 'fs';

const pdf = readFileSync('./invoice.pdf').toString('base64');

const result = await px.email.send({
  to: [{ email: 'jane@example.com', name: 'Jane Doe' }],
  subject: 'Your Invoice',
  html: '<p>Please find your invoice attached.</p>',
  attachments: [
    {
      filename: 'invoice.pdf',
      content: pdf,
      contentType: 'application/pdf',
    },
  ],
});

Error responses

Code	Description
BAD_REQUEST	Missing or invalid fields in the request body
FORBIDDEN	API key does not have the messaging:send scope
RATE_LIMITED	Rate limit exceeded for this API key