Public API Reference

Overview

The Temway Public API provides programmatic access to your workspace's emails, layouts, and branding. It supports both read (retrieve published content) and write operations (create, update, delete, duplicate), plus asynchronous rendering, publishing, and test sending. It is the same surface the Temway MCP server drives, and is designed for integrations with CMS platforms, automation tools, and custom applications.

Authentication is via API keys, which by default are scoped to a specific workspace and carry resource scopes that gate each endpoint. An owner or admin can instead create a key scoped to every workspace on the team — see List Workspaces. Keys are created and managed from the Developer entry in the Temway app's main sidebar.

Base URL

https://api.temway.com/api/v1/public

All Public API endpoints are prefixed with /api/v1/public. The paths below omit this prefix for brevity.

Authentication

Every request must include an API key in the Authorization header using the Bearer scheme:

Authorization: Bearer tmw_live_a1b2c3d4e5f67890abcdef12345678

API keys:

• Are prefixed with tmw_live_ followed by 32 hex characters
• Are scoped to a single workspace by default — a workspace-scoped key cannot access resources in other workspaces. An owner or admin can instead create a team-wide key, valid for every workspace on the team (see List Workspaces)
• Carry resource scopes that gate each endpoint (new keys default to all scopes, narrowable at create)
• Can have an optional expiration date
• Are hashed (SHA-256) at rest — the full key value is only shown once at creation time

Scopes

Each endpoint requires a specific scope. Keys created from the dashboard default to every scope; you can narrow a key to least privilege.

GET /branding requires emails:read or layouts:read. GET /me requires any valid key (no scope gate — it resolves the key itself). Authoring an email (emails:write) and pushing it to an ESP (espSync:write) are deliberately separate scopes — a key that can write emails cannot push to a third-party ESP unless granted espSync:write too.

Rate Limiting

The Public API applies per-key rate limits with in-memory sliding windows. Limits vary by endpoint group:

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1748354400
Retry-After: 18

The Retry-After header (seconds) is only present when the per-minute limit has been exceeded and the response status is 429. Test sends are additionally subject to a per-user rolling 24-hour cap derived from your plan (see Test Send Email) — that quota returns a separate error body.

Errors

The Public API returns consistent error responses with the following structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Pagination

List endpoints return paginated results with the following shape:

{
  "data": [
    { "id": "email_abc", "name": "Welcome Email", "...": "..." }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

Use the page and limit query parameters to navigate. Default limit is 20, maximum is 100.

Async Jobs (Export, Publish, Send)

Three email operations are asynchronous and follow a deliberate two-step pattern — you trigger a job, then poll it to completion by its explicit ID:

1. Export (POST /:id/export) enqueues a render job and returns { jobId, status } with HTTP 202. Each export renders exactly one target — email (MJML/table HTML) or web (semantic HTML5) — set by the target query param.
2. Publish (POST /:id/publish) consumes a completed target='web' render job (pass its renderJobId): copies the web HTML into the email, sets status='published', and snapshots a version.
3. Test send (POST /:id/test-send) consumes a completed target='email' render job (pass its renderJobId) and enqueues a send to the to address.

Poll render jobs via GET /:id/render-jobs/:jobId (or /latest) and send jobs via GET /:id/send-jobs/:jobId (or /latest). Always reference a render job by its explicit ID — never assume "latest completed", since a newer web-only publish job can shadow an email render.

Emails

All email endpoints are mounted under /workspaces/:workspaceId/emails.

List Published Emails

{
  "data": [
    {
      "id": "email_abc123",
      "name": "Welcome Email",
      "subject": "Welcome to Temway!",
      "preheaderText": "Get started with your account",
      "tags": ["onboarding"],
      "status": "published",
      "updatedAt": "2026-06-26T12:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Get Published Email

{
  "id": "email_abc123",
  "name": "Welcome Email",
  "subject": "Welcome to Temway!",
  "preheaderText": "Get started with your account",
  "tags": ["onboarding"],
  "status": "published",
  "updatedAt": "2026-06-26T12:00:00.000Z"
}

Get Published Email HTML

{
  "html": "<!DOCTYPE html>\n<html>...",
  "text": "Plain text version of the email...",
  "subject": "Welcome to Temway!",
  "preheaderText": "Get started with your account",
  "updatedAt": "2026-06-26T12:00:00.000Z"
}

Get Draft Email (for editing)

Create Email

{
  "name": "Welcome Email",          // required, 1–255 chars
  "subject": "Welcome to Temway!",  // optional
  "preheaderText": "Get started",   // optional
  "layoutId": "layout_abc123",      // optional — inherit a layout's content
  "tags": ["onboarding"],           // optional
  "content": { /* email-builder block tree */ }  // required
}

Update Email

{
  "name": "New Name",              // optional
  "subject": "...",                // optional, nullable
  "preheaderText": "...",          // optional, nullable
  "tags": ["newsletter"],          // optional
  "content": { /* block tree */ }, // optional
  "thumbnailUrl": "https://..."    // optional, nullable
}

Delete Email

Duplicate Email

{
  "name": "Copy of Welcome Email"  // optional — defaults to "Copy of <original>"
}

Create Email from Layout

{
  "layoutId": "layout_abc123",     // required
  "name": "Newsletter — June",     // required, 1–255 chars
  "subject": "Your June newsletter" // optional
}

Export (Render) Email

{
  "jobId": "rjob_xyz789",
  "status": "pending",
  "createdAt": "2026-07-02T10:00:00.000Z"
}

Get Render Job

{
  "id": "rjob_xyz789",
  "status": "completed",        // pending | processing | completed | failed
  "target": "email",
  "outputHtml": "<!DOCTYPE html>...",   // email target only (null for web)
  "outputHtmlWeb": null,                // web target only (null for email)
  "errorMessage": null,
  "createdAt": "2026-07-02T10:00:00.000Z",
  "completedAt": "2026-07-02T10:00:08.000Z"
}

Publish Email

{
  "renderJobId": "rjob_xyz789"   // required — must be a completed target='web' render
}

Test Send Email

{
  "to": "[email protected]",       // required — recipient email
  "renderJobId": "rjob_xyz789"   // required — must be a completed target='email' render
}

{
  "jobId": "sjob_qrs456",
  "status": "pending"
}

Get Send Job

{
  "id": "sjob_qrs456",
  "status": "completed",        // pending | processing | completed | failed
  "providerMessageId": "re_abc...",
  "errorMessage": null,
  "createdAt": "2026-07-02T10:01:00.000Z",
  "completedAt": "2026-07-02T10:01:03.000Z"
}

Layouts

All layout endpoints are mounted under /workspaces/:workspaceId/layouts. Layouts have no async render/export/send flow — publishing is synchronous.

List Published Layouts

{
  "data": [
    {
      "id": "layout_abc123",
      "name": "Newsletter Template",
      "description": "Two-column newsletter layout",
      "category": "newsletter",
      "tags": ["newsletter", "two-column"],
      "thumbnailUrl": "https://cdn.temway.com/thumbnails/layout_abc123.png",
      "status": "published",
      "updatedAt": "2026-06-26T12:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Get Published Layout

{
  "id": "layout_abc123",
  "name": "Newsletter Template",
  "description": "Two-column newsletter layout",
  "category": "newsletter",
  "tags": ["newsletter", "two-column"],
  "thumbnailUrl": "https://cdn.temway.com/thumbnails/layout_abc123.png",
  "status": "published",
  "updatedAt": "2026-06-26T12:00:00.000Z"
}

Get Draft Layout (for editing)

Create Layout

{
  "name": "Newsletter Template",          // required, 1–255 chars
  "description": "Two-column layout",     // optional, max 1000 chars
  "category": "newsletter",               // optional, max 50 chars
  "tags": ["newsletter"],                 // optional
  "canvas": { "width": 600, "height": 800 }, // optional
  "content": { /* layout-editor descriptor */ } // required
}

Update Layout

{
  "name": "New Name",                       // optional
  "description": "...",                     // optional, nullable
  "category": "...",                        // optional, nullable
  "tags": ["..."],                          // optional
  "canvas": { "width": 600, "height": 800 },// optional
  "content": { /* descriptor */ },          // optional
  "thumbnailUrl": "https://..."             // optional, nullable
}

Delete Layout

Duplicate Layout

{
  "name": "Copy of Newsletter Template"  // optional — defaults to "Copy of <original>"
}

Publish Layout

Branding

Get Workspace Branding

{
  "workspaceId": "ws_abc",
  "logoUrl": "https://cdn.temway.com/.../logo.png",
  "primaryColor": "#241A17",
  "fontFamily": "Inter",
  "fromName": "Temway",
  "updatedAt": "2026-06-26T12:00:00.000Z"
}

Integrations

Push a rendered email straight into a connected ESP as an editable template. Connecting an ESP account (and re-verifying or removing one) is dashboard-only — the public API surface is read + push.

List ESP Connections

[
  {
    "id": "conn_abc123",
    "provider": "mailchimp",
    "name": "Main list",
    "status": "active",        // active | error
    "lastError": null,
    "accountLabel": "Acme Co",
    "createdAt": "2026-06-01T12:00:00.000Z",
    "updatedAt": "2026-06-01T12:00:00.000Z"
  }
]

Push Email to ESP

{
  "renderJobId": "rjob_xyz789",       // required — must be a completed target='email' render
  "templateName": "June Newsletter"   // optional — defaults to the email's name
}

{
  "id": "sync_def456",
  "status": "pending",                // pending | processing | completed | failed
  "provider": "mailchimp",
  "templateName": "June Newsletter",
  "providerResourceId": null,
  "providerResourceUrl": null,
  "error": null,
  "emailId": "email_abc",
  "createdAt": "2026-08-10T12:00:00.000Z",
  "updatedAt": "2026-08-10T12:00:00.000Z",
  "completedAt": null
}

Get ESP Sync Status

{
  "id": "sync_def456",
  "status": "completed",
  "provider": "mailchimp",
  "templateName": "June Newsletter",
  "providerResourceId": "tpl_123",
  "providerResourceUrl": "https://mailchimp.com/templates/tpl_123",
  "error": null,
  "emailId": "email_abc",
  "createdAt": "2026-08-10T12:00:00.000Z",
  "updatedAt": "2026-08-10T12:00:05.000Z",
  "completedAt": "2026-08-10T12:00:05.000Z"
}

API Key

Get Current Key

{
  "workspaceId": "ws_abc",       // null for a team-wide key
  "defaultWorkspaceId": null,    // only present when workspaceId is null
  "teamId": "team_xyz",
  "scopes": ["emails:read", "emails:write", "layouts:read", "layouts:write", "espSync:read", "espSync:write"]
}

List Workspaces

[
  { "id": "ws_abc", "name": "Acme Co", "slug": "acme-co", "isDefault": true },
  { "id": "ws_def", "name": "Widgets Inc", "slug": "widgets-inc", "isDefault": false }
]

Quickstart

API keys are created from the Developer entry in the Temway app's main sidebar. Once you have a key, you can read published content, author new emails, render, publish, and test-send.

List published emails

curl https://api.temway.com/api/v1/public/workspaces/{workspaceId}/emails \
  -H "Authorization: Bearer tmw_live_a1b2c3d4e5f67890abcdef12345678"

Create an email, render, and publish

# 1. Create a draft email
curl -X POST https://api.temway.com/api/v1/public/workspaces/{workspaceId}/emails \
  -H "Authorization: Bearer tmw_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"June Newsletter","content":{...}}'

# 2. Render the WEB target (publish consumes a web render)
curl -X POST "https://api.temway.com/api/v1/public/workspaces/{workspaceId}/emails/{emailId}/export?target=web" \
  -H "Authorization: Bearer tmw_live_..."
# -> { "jobId": "rjob_xyz", "status": "pending" }

# 3. Poll the render job until status='completed'
curl https://api.temway.com/api/v1/public/workspaces/{workspaceId}/emails/{emailId}/render-jobs/{jobId} \
  -H "Authorization: Bearer tmw_live_..."

# 4. Publish using that render job
curl -X POST https://api.temway.com/api/v1/public/workspaces/{workspaceId}/emails/{emailId}/publish \
  -H "Authorization: Bearer tmw_live_..." \
  -H "Content-Type: application/json" \
  -d '{"renderJobId":"rjob_xyz"}'

Render inbox HTML and test-send

# 1. Render the EMAIL target (test sends consume an email render)
curl -X POST "https://api.temway.com/api/v1/public/workspaces/{workspaceId}/emails/{emailId}/export?target=email" \
  -H "Authorization: Bearer tmw_live_..."
# -> { "jobId": "rjob_abc", "status": "pending" }

# 2. Poll until completed, then test-send
curl -X POST https://api.temway.com/api/v1/public/workspaces/{workspaceId}/emails/{emailId}/test-send \
  -H "Authorization: Bearer tmw_live_..." \
  -H "Content-Type: application/json" \
  -d '{"to":"[email protected]","renderJobId":"rjob_abc"}'
# -> { "jobId": "sjob_def", "status": "pending" }

# 3. Poll the send job
curl https://api.temway.com/api/v1/public/workspaces/{workspaceId}/emails/{emailId}/send-jobs/{jobId} \
  -H "Authorization: Bearer tmw_live_..."

List published layouts

curl https://api.temway.com/api/v1/public/workspaces/{workspaceId}/layouts \
  -H "Authorization: Bearer tmw_live_a1b2c3d4e5f67890abcdef12345678"

Resolve your key

curl https://api.temway.com/api/v1/public/me \
  -H "Authorization: Bearer tmw_live_a1b2c3d4e5f67890abcdef12345678"
# -> { "workspaceId": "ws_abc", "teamId": "team_xyz", "scopes": [...] }