Emails API

Send transactional emails and retrieve sending history.

Send Email

POST /v1/send

Send a transactional email to one or more recipients.

Request Body

Example Request

curl -X POST https://api.postscale.io/v1/send \
  -H "Authorization: Bearer ps_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "orders@yourapp.com",
    "to": ["customer@example.com"],
    "subject": "Order Confirmation #12345",
    "html_body": "<h1>Thank you for your order!</h1><p>Order #12345 has been confirmed.</p>",
    "text_body": "Thank you for your order! Order #12345 has been confirmed.",
    "tags": ["order", "confirmation"],
    "metadata": {
      "order_id": "12345",
      "customer_id": "cust_abc"
    }
  }'

Example: Send with Template

curl -X POST https://api.postscale.io/v1/send \
  -H "Authorization: Bearer ps_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "orders@yourapp.com",
    "to": ["customer@example.com"],
    "template": "order-confirmation",
    "variables": {
      "first_name": "Jane",
      "order_id": "12345",
      "total": "$79.98"
    }
  }'

The template's subject, HTML body, and text body are rendered with the provided variables before sending. See Templates for details on template syntax.

Response

{
  "message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890@yourapp.com",
  "status": "queued",
  "warming_phase": "phase_1",
  "remaining_today": 1500,
  "remaining_this_hour": 100
}

List Emails

GET /v1/emails

Retrieve a list of sent emails with optional filtering.

Query Parameters

Example Request

curl -X GET "https://api.postscale.io/v1/emails?limit=50" \
  -H "Authorization: Bearer ps_live_your_api_key"

Response

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "from": "orders@yourapp.com",
    "to": "customer@example.com",
    "subject": "Order Confirmation #12345",
    "status": "delivered",
    "isp": "Gmail",
    "sent_at": "2026-01-18T10:30:01Z",
    "delivered_at": "2026-01-18T10:30:02Z"
  }
]

Get Email

GET /v1/emails/:id

Retrieve details for a specific email.

Example Request

curl -X GET https://api.postscale.io/v1/emails/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer ps_live_your_api_key"

Email Status Values

Batch Sending

POST /v1/send/batch

Send up to 100 emails in a single request.

Request

{
  "emails": [
    {
      "from": "newsletter@yourapp.com",
      "to": ["user1@example.com"],
      "subject": "Newsletter",
      "html_body": "<p>Hello User 1</p>"
    },
    {
      "from": "newsletter@yourapp.com",
      "to": ["user2@example.com"],
      "subject": "Newsletter",
      "html_body": "<p>Hello User 2</p>"
    }
  ]
}

Response

{
  "queued": 2,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "message_id": "a1b2c3d4@yourapp.com",
      "status": "queued"
    },
    {
      "index": 1,
      "message_id": "e5f67890@yourapp.com",
      "status": "queued"
    }
  ],
  "warming_phase": "phase_1",
  "remaining_today": 1498,
  "remaining_this_hour": 98
}

Batch Sending with Templates

Each email in a batch can use a template instead of inline content. Templates are resolved once per unique slug/ID for efficiency:

{
  "emails": [
    {
      "from": "orders@yourapp.com",
      "to": ["user1@example.com"],
      "template": "order-confirmation",
      "variables": { "first_name": "Alice", "order_id": "001" }
    },
    {
      "from": "orders@yourapp.com",
      "to": ["user2@example.com"],
      "template": "order-confirmation",
      "variables": { "first_name": "Bob", "order_id": "002" }
    }
  ]
}