Send an operational email from a Business Action

Requires the trusted Business Actions SDK relay with declared emails.send and Write on the workspace email resource. Use platform.withStep(stepId).emails.send(). The automatic workspace address supplies From. Text is required; HTML is optional. Up to 10 recipients and 200 KB. Receipts indicate acceptance, not delivery; successful steps replay and uncertain sends are never automatically retried.

POST/v1/emails

betaauthenticatedworkspace

When to use

Send an operational message from a published Business Action.

For agents

This endpoint only accepts the trusted action SDK relay. Ordinary REST requests and direct SDK sends are denied. Declare emails.send and sender Write access, then call platform.withStep(stepId).emails.send inside the handler. The result confirms acceptance (delivery is asynchronous). Successful steps replay; uncertain sends require checking external state before another invocation. Limits are 10 visible To recipients, 200 KB, and 1,000 recipient attempts per workspace per UTC day. Do not use for unsolicited outreach or marketing.

Example

typescript

import { PermuteClient } from '@permute/sdk';

const orgClient = new PermuteClient({
  apiKey: process.env.PERMUTE_API_KEY!,
});

const client = orgClient.withWorkspace(process.env.PERMUTE_WORKSPACE_ID!);

const result = await // Inside a published Business Action handler:
await platform.withStep('send-order-update').emails.send({
  "to": [
    "customer@example.com"
  ],
  "subject": "Order ready",
  "text": "Order 123 is ready.",
  "html": "<p>Order <strong>123</strong> is ready.</p>"
});

Request body

json

{
  "to": [
    "customer@example.com"
  ],
  "subject": "Order ready",
  "text": "Order 123 is ready.",
  "html": "<p>Order <strong>123</strong> is ready.</p>"
}

Response

json

{
  "data": {
    "id": "ses-message-id",
    "status": "accepted"
  }
}