Sitelet https://docs.unlayer.com/server/cloud-api
Skip to main content
Unlayer Docs

Cloud API

The Cloud API is the server-side interface to Unlayer. It runs outside the browser and lets your backend:

  • Send transactional email from your own verified domains, with delivery tracking, webhooks, and suppression handling
  • Generate artifacts (HTML, PDF, Image, ZIP) from a design JSON
  • Manage templates stored in your Unlayer project
  • List blocks — shared and end-user saved — for backup and usage reporting
  • Convert designs between Full and Simple schema forms
  • Validate a design against the Unlayer schema
  • Execute secure operations that should not run in the browser

View the full API reference →

When to use the Cloud API​

Reach for the Cloud API when:

  • You want to send transactional email (welcome, receipts, password resets) from your own domain without running your own SMTP/ESP integration
  • You need to generate a PDF from a design in a background job
  • You want to export HTML without exposing API keys to the browser
  • You want to generate an image preview server-side
  • You are running a cron job, webhook handler, or worker process
  • You need to validate or convert a design payload before storing or rendering it
Embedding the builder?

If your use case involves embedding a visual builder or editor in your frontend, see Builders instead.

How it works​

Most server workflows follow this pattern:

Server workflow: design JSON from browser to backend; Cloud API returns artifact

  1. A Builder produces a design JSON (in the browser).
  2. Your backend sends that JSON to the Cloud API.
  3. The API returns a generated artifact (HTML, PDF, Image, ZIP) — or a validated / converted design payload.
  4. You store, send, or distribute the result.
Exporting HTML

For HTML export, you often don't need the Cloud API — the builder can produce HTML directly in the browser via unlayer.exportHtml(). Use the Cloud API when you need to export HTML server-side (for example, in a background job or when the user is not in the builder).

Sending email​

Send transactional email from a verified domain using raw HTML or a saved template. Email Sending is in private beta and requires workspace access.

Use POST /v3/emails for HTML or POST /v3/emails/template for a template. A new accepted send returns 202 and an email ID. Track delivery with webhooks or the email detail endpoint, and use an Idempotency-Key when retrying a request.

See the Email Sending guide for authentication, domain verification, limits, and complete examples.

Security model​

The Cloud API uses bearer-token authentication — API Key, Personal Access Token, or OAuth. See Authentication for token types, how to get each one from Console, and security guidelines.

Traffic protection​

Infrastructure protection is separate from your plan's usage allowance. When enabled, protected server-side operations (exports and rendering, AI generation, and template, block and other reads and writes) share their workspace's capacity across projects and credentials. Each kind of work has its own capacity, so heavy exports do not slow down routine reads. Test projects also use this capacity.

An exhausted capacity bucket returns HTTP 429 with error code INFRASTRUCTURE_RATE_LIMITED and a Retry-After header in seconds. Wait at least that long before retrying, spread retries out, and reduce concurrent requests. Do not automatically replay a write unless the operation supports safe retries. Changing credentials does not create another allowance. Rejected operations do not start the expensive work or consume usage credits.

An operation that is too large to fit the configured capacity returns HTTP 400 with OPERATION_TOO_LARGE; reduce its batch size instead of retrying it unchanged. Browser-local HTML export does not call the server and is unaffected.

Keep tokens server-side

Tokens grant full access to your project's data:

  • Never call the Cloud API directly from the browser
  • Always proxy requests through your backend
  • Keep tokens in secure server-side environments only

Typical use cases​

Use caseDescription
Send transactional emailDeliver receipts, password resets, and notifications from your verified domain via POST /v3/emails.
Export PDF in background jobGenerate a PDF after a user submits a form, then email it automatically.
Generate HTML for email sendingExport HTML server-side and send it via the Send API — or pass it to your own email provider.
Image thumbnail generationGenerate preview images for templates or documents.
ZIP export for asset bundlesProduce downloadable packages including images and required assets.
Validate user-supplied designsCheck that an imported or uploaded design conforms to the schema.
Convert between schema formsRound-trip designs between the editor's Full shape and the wire Simple shape.

What's next​

  • See the API reference for the full endpoint list.
  • See Design Schema for the shape of the design JSON the API accepts and returns.
  • If you're embedding the builder, go to Builders.