REST API V18 min read•Audience: Developers, DevOps, Backend Engineers

PostBrix REST API Reference

Automate transactional receipts, lifecycle digests, and marketing email rendering with the PostBrix rendering engine. Generate client-tested, responsive HTML and MJML programmatically from your applications and microservices.

Key Architecture Highlights

Base API Endpoint: https://apidev.postbrix.com/v1
Authentication: Bearer token authentication with scoped API keys (pb_live_...) passed in the standard HTTP Authorization header.
Sub-50ms Latency: P95 response times under 50ms powered by in-memory JSON AST compilation and distributed Redis caching.
Universal ESP Compatibility: Clean, responsive MJML and inlined HTML ready for immediate sending through SendGrid, Mailchimp, Klaviyo, Brevo, AWS SES, or Postmark.

Overview & Base URL

The PostBrix API is organized around REST. All requests must use the HTTPS protocol with JSON-encoded request bodies and return standard HTTP response codes and JSON bodies (except dynamic preview endpoints which return raw HTML).

Root Endpoint URLhttps://apidev.postbrix.com/v1

Quickstart Ping (cURL)

bash

Verifies network connectivity and authentication against the rendering cluster.

curl -X GET "https://apidev.postbrix.com/v1/health" \
  -H "Authorization: Bearer pb_live_your_api_key" \
  -H "Content-Type: application/json"

Authentication

PostBrix authenticates API requests using Secret API Keys. Your API keys carry full privileges to render your organization’s templates and project data. Always store them securely using server-side environment variables or secret vaults.

Keep API Keys Confidential

Never commit API keys to version control (Git) or include them in client-side code (browsers or mobile applications). All requests must originate from secure server-side runtimes over HTTPS.

Key Format

All production keys begin with the prefix pb_live_ followed by 32 cryptographically secure hexadecimal characters.

Key Management

Generate, rotate, or revoke keys at any time from your PostBrix dashboard under Settings → API Keys.

HTTP Authorization Header

http

Include this header in every request to authenticated endpoints.

Authorization: Bearer pb_live_a1b2c3d4e5f67890abcdef1234567890

Rate Limiting

To guarantee consistent latency and protect shared infrastructure, PostBrix enforces a sliding-window rate limit evaluated at the organization level across all endpoints.

Subscription Tier	Rate Limit	Window	Burst Allowance
Free Developer	5 req/min	60 seconds	10 requests
Pro Plan	60 req/min	60 seconds	100 requests
Enterprise Plan	300+ req/min	60 seconds	Custom dedicated SLA

HTTP 429 Status & Response Headers

When rate limits are exceeded, the API responds with HTTP 429 Too Many Requests. Inspect the Retry-After header for the number of seconds to wait before retrying.

Core Endpoints

PostBrix provides dedicated endpoints for project rendering, template rendering, and live preview generation.

Method	Endpoint Path	Description
POST	/api/render-email	Render saved email structure by project ID with dynamic merge values.
POST	/v1/templates/:templateId/render	High-throughput template render endpoint with Redis caching.
GET	/api/render-email/:projectId	Raw HTML preview stream for iframe embedding and live customer portals.

POST/api/render-email

The primary endpoint for transactional email triggers. Fetches the latest visual email layout designed in the PostBrix Studio and evaluates Handlebars variables in one call.

Request Parameters

Field	Type	Requirement	Description
projectId	string	Required	Unique project identifier from the PostBrix dashboard URL (e.g. `cmuhceoo1000201ph972mxpzv`).
data	object	Optional	Key-value map of dynamic Handlebars variables to merge into the template layout.

POST /api/render-email Request Body

json

{
  "projectId": "cmuhceoo1000201ph972mxpzv",
  "data": {
    "userName": "Jane Doe",
    "orderId": "#ORD-2026-9811",
    "items": [
      { "name": "Annual SaaS License", "price": "$299.00" },
      { "name": "Priority Support Add-on", "price": "$49.00" }
    ],
    "accountUrl": "https://company.com/billing"
  }
}

Response (200 OK)

json

{
  "success": true,
  "html": "<!doctype html><html xmlns=\"http://www.w3.org/1999/xhtml\">...</html>",
  "plainHtml": "<html>...</html>",
  "renderDurationMs": 34,
  "cached": true,
  "errors": []
}

POST/v1/templates/:templateId/render

The recommended endpoint for high-scale backend services, microservices, and serverless runtimes. Features automatic Redis multi-tier caching and parallelized MJML worker compilation.

TypeScript / Node.js Implementation

typescript

Type-safe SDK invocation with automatic retries and response validation.

import { PostBrix } from '@postbrix/sdk';

const postbrix = new PostBrix({
  apiKey: process.env.POSTBRIX_API_KEY!,
});

async function sendWelcomeEmail(userEmail: string, name: string) {
  // Render template by CUID template ID (e.g. 'cmuhceoo1000201ph972mxpzv')
  const { html } = await postbrix.render('cmuhceoo1000201ph972mxpzv', {
    name,
    loginUrl: 'https://app.yourdomain.com/login',
  });

  // Dispatch via your configured ESP (e.g. SendGrid or Postmark)
  await sendgrid.send({
    to: userEmail,
    from: 'support@yourdomain.com',
    subject: 'Welcome to the platform!',
    html,
  });
}

GET/api/render-email/:projectId

Returns raw text/html directly for easy embedding in iframes, customer webview portals, or mobile app preview screens.

Query Parameters

Parameter	Type	Required	Description
token	string	Optional	Project share token for unauthenticated preview access from third-party dashboards.
data	string	Optional	URI-encoded JSON string containing merge values to inject into the live render.

Embedding Live HTML Preview in an iframe

html

<iframe
  src="https://apidev.postbrix.com/api/render-email/cmuhceoo1000201ph972mxpzv?token=tok_share_abc&data=%7B%22name%22%3A%22Jane%22%7D"
  width="100%"
  height="700"
  style="border: none; border-radius: 12px;"
  title="Email Preview"
/>

Error Codes & Handling

PostBrix returns standard HTTP response status codes. Every 4xx and 5xx error includes a structured JSON body describing the exact error code and human-readable context.

Status Code	Reason	Resolution
200 OK	Success	HTML compiled and returned.
400 Bad Request	Invalid Payload	Verify request body matches JSON schema.
401 Unauthorized	Missing / Invalid API Key	Check Authorization Bearer header.
404 Not Found	Template Not Found	Confirm project or template ID exists in workspace.
429 Rate Limit	Rate Limit Exceeded	Inspect Retry-After header and back off.
500 Server Error	Compilation Failure	Contact PostBrix API engineering support.

Structured JSON Error Example

json

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Your tier allows 60 requests per minute.",
    "retryAfterSeconds": 14
  }
}

Explore More Developer Guides

Client SDKs

Node.js, Python, and Go code samples with retry policies.

JSON Schema (AST)

Inspect the EmailBlock AST and block properties.

Rendering Pipeline

4-stage compilation, worker threads, and caching.

Need custom API integration or higher throughput?

Our engineering team assists enterprise customers with dedicated proxies, SLAs, and custom endpoints.

Contact Engineering

REST API V18 min read•Audience: Developers, DevOps, Backend Engineers

PostBrix REST API Reference

Key Architecture Highlights

Base API Endpoint: https://apidev.postbrix.com/v1
Authentication: Bearer token authentication with scoped API keys (pb_live_...) passed in the standard HTTP Authorization header.
Sub-50ms Latency: P95 response times under 50ms powered by in-memory JSON AST compilation and distributed Redis caching.
Universal ESP Compatibility: Clean, responsive MJML and inlined HTML ready for immediate sending through SendGrid, Mailchimp, Klaviyo, Brevo, AWS SES, or Postmark.

Overview & Base URL

Root Endpoint URLhttps://apidev.postbrix.com/v1

Quickstart Ping (cURL)

bash

Verifies network connectivity and authentication against the rendering cluster.

curl -X GET "https://apidev.postbrix.com/v1/health" \
  -H "Authorization: Bearer pb_live_your_api_key" \
  -H "Content-Type: application/json"

Authentication

Keep API Keys Confidential

Never commit API keys to version control (Git) or include them in client-side code (browsers or mobile applications). All requests must originate from secure server-side runtimes over HTTPS.

Key Format

All production keys begin with the prefix pb_live_ followed by 32 cryptographically secure hexadecimal characters.

Key Management

Generate, rotate, or revoke keys at any time from your PostBrix dashboard under Settings → API Keys.

HTTP Authorization Header

http

Include this header in every request to authenticated endpoints.

Authorization: Bearer pb_live_a1b2c3d4e5f67890abcdef1234567890

Rate Limiting

To guarantee consistent latency and protect shared infrastructure, PostBrix enforces a sliding-window rate limit evaluated at the organization level across all endpoints.

Subscription Tier	Rate Limit	Window	Burst Allowance
Free Developer	5 req/min	60 seconds	10 requests
Pro Plan	60 req/min	60 seconds	100 requests
Enterprise Plan	300+ req/min	60 seconds	Custom dedicated SLA

HTTP 429 Status & Response Headers

When rate limits are exceeded, the API responds with HTTP 429 Too Many Requests. Inspect the Retry-After header for the number of seconds to wait before retrying.

Core Endpoints

PostBrix provides dedicated endpoints for project rendering, template rendering, and live preview generation.

Method	Endpoint Path	Description
POST	/api/render-email	Render saved email structure by project ID with dynamic merge values.
POST	/v1/templates/:templateId/render	High-throughput template render endpoint with Redis caching.
GET	/api/render-email/:projectId	Raw HTML preview stream for iframe embedding and live customer portals.

POST/api/render-email

The primary endpoint for transactional email triggers. Fetches the latest visual email layout designed in the PostBrix Studio and evaluates Handlebars variables in one call.

Request Parameters

Field	Type	Requirement	Description
projectId	string	Required	Unique project identifier from the PostBrix dashboard URL (e.g. `cmuhceoo1000201ph972mxpzv`).
data	object	Optional	Key-value map of dynamic Handlebars variables to merge into the template layout.

POST /api/render-email Request Body

json

{
  "projectId": "cmuhceoo1000201ph972mxpzv",
  "data": {
    "userName": "Jane Doe",
    "orderId": "#ORD-2026-9811",
    "items": [
      { "name": "Annual SaaS License", "price": "$299.00" },
      { "name": "Priority Support Add-on", "price": "$49.00" }
    ],
    "accountUrl": "https://company.com/billing"
  }
}

Response (200 OK)

json

{
  "success": true,
  "html": "<!doctype html><html xmlns=\"http://www.w3.org/1999/xhtml\">...</html>",
  "plainHtml": "<html>...</html>",
  "renderDurationMs": 34,
  "cached": true,
  "errors": []
}

POST/v1/templates/:templateId/render

The recommended endpoint for high-scale backend services, microservices, and serverless runtimes. Features automatic Redis multi-tier caching and parallelized MJML worker compilation.

TypeScript / Node.js Implementation

typescript

Type-safe SDK invocation with automatic retries and response validation.

import { PostBrix } from '@postbrix/sdk';

const postbrix = new PostBrix({
  apiKey: process.env.POSTBRIX_API_KEY!,
});

async function sendWelcomeEmail(userEmail: string, name: string) {
  // Render template by CUID template ID (e.g. 'cmuhceoo1000201ph972mxpzv')
  const { html } = await postbrix.render('cmuhceoo1000201ph972mxpzv', {
    name,
    loginUrl: 'https://app.yourdomain.com/login',
  });

  // Dispatch via your configured ESP (e.g. SendGrid or Postmark)
  await sendgrid.send({
    to: userEmail,
    from: 'support@yourdomain.com',
    subject: 'Welcome to the platform!',
    html,
  });
}

GET/api/render-email/:projectId

Returns raw text/html directly for easy embedding in iframes, customer webview portals, or mobile app preview screens.

Query Parameters

Parameter	Type	Required	Description
token	string	Optional	Project share token for unauthenticated preview access from third-party dashboards.
data	string	Optional	URI-encoded JSON string containing merge values to inject into the live render.

Embedding Live HTML Preview in an iframe

html

<iframe
  src="https://apidev.postbrix.com/api/render-email/cmuhceoo1000201ph972mxpzv?token=tok_share_abc&data=%7B%22name%22%3A%22Jane%22%7D"
  width="100%"
  height="700"
  style="border: none; border-radius: 12px;"
  title="Email Preview"
/>

Error Codes & Handling

PostBrix returns standard HTTP response status codes. Every 4xx and 5xx error includes a structured JSON body describing the exact error code and human-readable context.

Status Code	Reason	Resolution
200 OK	Success	HTML compiled and returned.
400 Bad Request	Invalid Payload	Verify request body matches JSON schema.
401 Unauthorized	Missing / Invalid API Key	Check Authorization Bearer header.
404 Not Found	Template Not Found	Confirm project or template ID exists in workspace.
429 Rate Limit	Rate Limit Exceeded	Inspect Retry-After header and back off.
500 Server Error	Compilation Failure	Contact PostBrix API engineering support.

Structured JSON Error Example

json

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Your tier allows 60 requests per minute.",
    "retryAfterSeconds": 14
  }
}

Need custom API integration or higher throughput?

Our engineering team assists enterprise customers with dedicated proxies, SLAs, and custom endpoints.

Contact Engineering