---
title: "Preview a rule that is not saved yet"
method: POST
path: "/v1/email-rules/preview"
tags: ["Email"]
---

# Preview a rule that is not saved yet

`POST /v1/email-rules/preview`

## Request

- Base URL: `https://api-eu.dynamicdocumentapi.com`
- URL: `https://api-eu.dynamicdocumentapi.com/v1/email-rules/preview`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

A watermarked preview render of the template (its live version, else its draft) with the rule's email rendered in the document's context: the fields, the recipients as parsed and the attachments as they would be planned. Nothing is sent and nothing is billed. The data is `data`, else the dataset `dataset_id`, else the template's default dataset, else `{}`. `rule.connection_id` names the connection.

## Request body

- EmailRuleDraftPreviewRequest: `POST /v1/email-rules/preview`: a rule that has not been saved yet.
  - `data` object, nullable
  - `dataset_id` string, nullable
  - `rule` EmailRuleSpec, required: The editable fields of an email rule, as the rule editor holds them (unsaved state). Used instead of the saved rule; fields the editor does not know (`name`, `enabled`, …) are ignored. `null` counts as empty. Syntax errors come back as the preview's `email_preview.error`.
    - `attach_formats` string[], nullable
    - `attachments` 'attach_or_link' | 'attach' | 'link' | 'none', nullable
    - `bcc` string, nullable
    - `cc` string, nullable
    - `condition` string, nullable
    - `connection_id` string, nullable: `emc_…`; defaults to the saved rule's connection.
    - `from_email` string, nullable
    - `from_name` string, nullable
    - `html` string, nullable
    - `provider_template` EmailProviderTemplateSpec: A Brevo template the rule sends instead of its own body; Brevo connections only.
      - `id` integer, required: The template id in the Brevo account.
      - `params` string: Template source that must render to a JSON object (Brevo's `params`).
    - `reply_to` string, nullable
    - `subject` string, nullable
    - `text` string, nullable
    - `to` string, nullable
  - `template_id` string, required

## Response `200`

- RenderWithEmailPreview
  - `batch_id` string, nullable
  - `billed_renders` integer: Renders billed for this request (0 for test renders, previews, failed and canceled renders).
  - `completed_at` string, date-time, nullable
  - `created_at` string, date-time, required
  - `email` RenderEmail[]: The render's email sends in creation order. They are created when the render's result is processed, so a render still running (or a sync response) lists none yet; `render.succeeded` shows them as created: `pending`, or `skipped` / `failed`.
    - `error` EmailSendError, required: Why a send failed or waits: never message bodies or addresses.
      - `code` string, required: `email_template_error`, `email_too_large`, `email_recipient_missing`, `email_address_invalid`, `email_too_many_recipients`, `email_attachment_too_large`, `email_attachment_type_not_allowed`, `email_needs_hosted_file`, `email_provider_rejected`, `email_provider_auth_failed`, `email_provider_unavailable`, `email_ip_not_authorized`, `email_rate_limited`, `email_outcome_unknown`, `email_daily_cap_reached`, `email_disabled`, `email_credentials_removed`, `email_send_expired`, `internal_error`
      - `column` integer
      - `field` string: `email_template_error`, `email_too_large`: the rule field, e.g. `subject`.
      - `line` integer: `email_template_error`: where in the field.
      - `message` string, required
      - `provider_code` string, nullable: The provider's own error code.
      - `provider_status` integer, nullable: The provider's HTTP or SMTP status.
    - `id` string, required
    - `provider_message_id` string, nullable, required
    - `rule_id` string, required
    - `sent_at` string, date-time, nullable, required
    - `status` 'pending' | 'sending' | 'retrying' | 'sent' | 'sandboxed' | 'skipped' | 'failed' | 'unknown' | 'canceled', required
    - `to` string[], required: The `to` addresses.
  - `engine` string
  - `engine_version` string, nullable
  - `error` RenderError
    - `code` string
    - `column` integer
    - `detail` string
    - `excerpt` string
    - `line` integer
    - `message` string
  - `expires_at` string, date-time, nullable
  - `files` RenderFile[], required
    - `bytes` integer, required
    - `content_base64` string: Only with `delivery.type=base64`.
    - `content_type` string
    - `filename` string, required
    - `format` 'pdf' | 'png' | 'jpeg' | 'webp' | 'html' | 'zip' | 'xml', required
    - `height` integer, nullable
    - `id` string, required
    - `pages` integer, nullable
    - `sha256` string
    - `url` string, uri: Signed URL (omitted when not hosted).
    - `url_expires_at` string, date-time
    - `variant` string, nullable
    - `width` integer, nullable
  - `id` string, required
  - `input_type` 'template' | 'html' | 'url' | 'markdown' | 'pdf_tool' | 'einvoice'
  - `kind` string
  - `metadata` object
  - `mode` 'sync' | 'async', required
  - `object` 'render', required
  - `output_format` 'pdf' | 'png' | 'jpeg' | 'webp' | 'html' | 'zip' | 'xml'
  - `pages` integer, nullable
  - `reference` string, nullable
  - `region` string, required
  - `result` RenderResult: Structured result, `null` for most renders. PDF/A, PDF/UA, tagged and e-invoice renders carry their conformance report here — succeeded **and** failed ones; `pdf-tools/metadata` without `set` returns the document information (`pages`, `page_sizes`, `encrypted`, `metadata`).
    - `conformance` ConformanceReport: Validation of the delivered file against the standards it claims.
      - `einvoice` EInvoiceConformance
        - `errors` ConformanceFinding[], required
          - `count` integer, required
          - `location` string, required: JSON path into the invoice for model issues found before the XML was written, else the validator's XPath or veraPDF context; empty when the finding concerns the whole document (e.g. a PDF/A `conversion` error).
          - `message` string, required
          - `rule` string, required: Business rule (EN 16931 `BR-…`, XRechnung `BR-DE-…`), schema rule, or PDF/A or PDF/UA clause and test number (`6.2.4.3-2`, `7.3-1`).
        - `profile` 'MINIMUM' | 'BASIC_WL' | 'BASIC' | 'EN16931' | 'EXTENDED' | 'XRECHNUNG', required
        - `scenario` string, nullable, required: The validator scenario that matched; `null` when it did not run.
        - `status` 'passed' | 'failed' | 'unavailable', required: `unavailable`: the validator was not configured or did not answer in time; the file was delivered unvalidated (warning `einvoice_validation_unavailable`).
        - `syntax` 'cii' | 'ubl', required
        - `validator` string, nullable, required: `null` when the validator did not run (`einvoice_invalid`: the model broke a rule before any XML was written, or unavailable).
        - `warnings` ConformanceFinding[], required
          - `count` integer, required
          - `location` string, required: JSON path into the invoice for model issues found before the XML was written, else the validator's XPath or veraPDF context; empty when the finding concerns the whole document (e.g. a PDF/A `conversion` error).
          - `message` string, required
          - `rule` string, required: Business rule (EN 16931 `BR-…`, XRechnung `BR-DE-…`), schema rule, or PDF/A or PDF/UA clause and test number (`6.2.4.3-2`, `7.3-1`).
      - `pdfa` PdfaConformance
        - `errors` ConformanceFinding[], required
          - `count` integer, required
          - `location` string, required: JSON path into the invoice for model issues found before the XML was written, else the validator's XPath or veraPDF context; empty when the finding concerns the whole document (e.g. a PDF/A `conversion` error).
          - `message` string, required
          - `rule` string, required: Business rule (EN 16931 `BR-…`, XRechnung `BR-DE-…`), schema rule, or PDF/A or PDF/UA clause and test number (`6.2.4.3-2`, `7.3-1`).
        - `level` '2b' | '3b', required
        - `profile` string, nullable, required: veraPDF validation profile; `null` when veraPDF did not run.
        - `status` 'passed' | 'failed' | 'unavailable', required: `unavailable`: the validator was not configured or did not answer in time; the file was delivered unvalidated (warning `pdfa_validation_unavailable`).
        - `validator` string, nullable, required: `null` when veraPDF did not run (conversion failed, or unavailable).
        - `warnings` ConformanceFinding[], required
          - `count` integer, required
          - `location` string, required: JSON path into the invoice for model issues found before the XML was written, else the validator's XPath or veraPDF context; empty when the finding concerns the whole document (e.g. a PDF/A `conversion` error).
          - `message` string, required
          - `rule` string, required: Business rule (EN 16931 `BR-…`, XRechnung `BR-DE-…`), schema rule, or PDF/A or PDF/UA clause and test number (`6.2.4.3-2`, `7.3-1`).
      - `pdfua` PdfuaConformance: veraPDF's PDF/UA-1 check of a render with `pdf.pdfua` or `pdf.tagged`. With `pdfua`, `failed` fails the render (`pdfua_validation_failed`); with `tagged` alone, and in previews, the report is information. The machine checks don't judge whether alt text is meaningful or the reading order right.
        - `errors` ConformanceFinding[], required
          - `count` integer, required
          - `location` string, required: JSON path into the invoice for model issues found before the XML was written, else the validator's XPath or veraPDF context; empty when the finding concerns the whole document (e.g. a PDF/A `conversion` error).
          - `message` string, required
          - `rule` string, required: Business rule (EN 16931 `BR-…`, XRechnung `BR-DE-…`), schema rule, or PDF/A or PDF/UA clause and test number (`6.2.4.3-2`, `7.3-1`).
        - `profile` string, nullable, required: veraPDF validation profile; `null` when veraPDF did not run.
        - `standard` 'PDF/UA-1', required
        - `status` 'passed' | 'failed' | 'unavailable', required: `unavailable`: the validator was not configured or did not answer in time; the file was delivered unvalidated (warning `pdfua_validation_unavailable`).
        - `validator` string, nullable, required: `null` when veraPDF did not run (the title or language was missing, or unavailable).
        - `warnings` ConformanceFinding[], required
          - `count` integer, required
          - `location` string, required: JSON path into the invoice for model issues found before the XML was written, else the validator's XPath or veraPDF context; empty when the finding concerns the whole document (e.g. a PDF/A `conversion` error).
          - `message` string, required
          - `rule` string, required: Business rule (EN 16931 `BR-…`, XRechnung `BR-DE-…`), schema rule, or PDF/A or PDF/UA clause and test number (`6.2.4.3-2`, `7.3-1`).
  - `source` string
  - `status` 'queued' | 'processing' | 'succeeded' | 'failed' | 'canceled' | 'expired', required
  - `storage` StorageResult[]
    - `destination_id` string
    - `error` string, nullable
    - `location` string, nullable
    - `status` 'pending' | 'succeeded' | 'failed' | 'skipped'
  - `template` object, nullable
    - `id` string
    - `version` union
      - integer
      - string
    - `version_id` string, nullable
  - `test` boolean, required
  - `timings` object
  - `warnings` object[]: Non-fatal: `slow_asset`, `asset_failed`, `wait_timeout` (the wait condition timed out and `wait.strict` is off, so the page was rendered as it was), `header_footer_overlap` (a header or footer is taller than its margin and may cover the body), `locale_unsupported` (the engine doesn't support `locale`), `feature_unavailable` (something in the request or template was ignored; the message names it), `font_fallback_used` (canvas templates: an unavailable font was replaced by Noto Sans; HTML renders fall back silently), `data_coerced` (canvas templates: a data value couldn't be used as given), `text_overflow` (canvas templates: text was cut off or overflows its box), `storage_upload_failed`, `einvoice_validation_warning`, `einvoice_validation_unavailable`, `pdfa_validation_unavailable`, `pdfua_validation_unavailable` (veraPDF was not reachable: the PDF/UA file is delivered unvalidated), `accessibility_validation_unavailable` (`tagged` without `pdfua`: no PDF/UA report, veraPDF was not reachable), `einvoice_skipped_plan`, `storage_skipped_plan`, `email_skipped_plan` (the template's email rules need the Growth plan or higher; no email was sent), `email_skipped_zero_retention` (zero-retention renders have no file to email), `invoice_totals_unavailable`.
    - `code` string
    - `message` string
  - `email_preview` EmailPreview, required: What the rule would send for the previewed render; nothing is sent. `send` is false with `skip_reason` (the condition is false) or `error` (a template error, the recipients or the attachments). `html` and `text` keep the marker that becomes the download links when sending; an empty `text` is derived from `html` when sending.
    - `attachments` EmailSendAttachment[], required
      - `bytes` integer, required
      - `file_id` string, required
      - `filename` string, required
      - `mode` 'attached' | 'linked', required: `linked`: a download link valid until the file's retention ends, at most 7 days.
    - `bcc` EmailMailbox[], required
      - `email` string, required
      - `name` string, nullable
    - `cc` EmailMailbox[], required
      - `email` string, required
      - `name` string, nullable
    - `error` RenderError, required
      - `code` string
      - `column` integer
      - `detail` string
      - `excerpt` string
      - `line` integer
      - `message` string
    - `from_email` string, required
    - `from_name` string, nullable, required
    - `html` string, required
    - `provider_template` object, nullable
      - `id` integer
      - `params` object
    - `recipient_errors` string[]: Every recipient entry that is not an address.
    - `reply_to` string, nullable, required
    - `send` boolean, required
    - `skip_reason` 'condition_false', nullable, required
    - `subject` string, required
    - `text` string, required
    - `to` EmailMailbox[], required
      - `email` string, required
      - `name` string, nullable

## Other responses

- `202`: The preview did not finish within the sync wait (`email_preview: null`).
- `400`: Invalid request (`errors[]`), e.g. an unknown `rule.connection_id`.
- `401`: Missing, invalid, expired or revoked credentials.
- `402`: Email delivery needs the Growth plan or higher (`plan_feature_unavailable`).
- `403`: Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified.
- `404`: Rule, template, connection or dataset not found.
- `410`: Template deleted.
- `422`: The document failed to render (`render_error`).
- `429`: Rate limited (`Retry-After`).
- `503`: Region degraded or the email checks are unavailable (`Retry-After`).

---

[API](https://skmtc.dev/dynamicdocumentapi/apis/dynamic-document-api.md) · [All operations](https://skmtc.dev/dynamicdocumentapi/apis/dynamic-document-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dynamicdocumentapi/apis/dynamic-document-api/revisions/0f14bc0000f4?raw)