KNknak
Assets

Trigger a marketing platform sync

Trigger a sync of an asset to a marketing platform. Returns 202 Accepted with a marketing platform sync record whose id can be polled via GET /marketing-platform-syncs/{id}.

Platform support: only integrations with platform marketing_cloud (Salesforce Marketing Cloud) are currently supported. Requests targeting other platforms return 422 Unprocessable Entity with a validation error on integration_id. Additional platforms will be enabled in future releases.

Returns 409 Conflict when another sync is already pending or in progress for the same asset + integration pair. The conflict response includes meta.existing_sync_id so the caller can poll that sync instead.

Returns 422 Unprocessable Entity when sync_type is resync but the asset has never been successfully synced to the target integration.

Pre-sync Audit Validation

Before queuing a sync, Knak runs a pre-sync audit against the asset. When the audit finds blocking errors, the request returns 422 Unprocessable Entity with a meta.pre_sync_validation block. When the audit passes (with or without non-blocking warnings), the request returns 202 Accepted and the same meta.pre_sync_validation block is included with details. Privileged callers can opt out of audit enforcement by setting skip_optimize_validation: true (requires the emails_bypass_optimize_sync permission).

Note: "pre-sync audit" refers to Knak's structural and content checks on the asset (image alt text, email size, expired modules, etc.). It is not the LLM-based brand-voice "Optimize Checks" feature, which shares a name in the product UI but does not run on the Sync API today.

Audit Result Shape

Each entry in errors[], warnings[], and asset_exceptions[] has the shape { id, message, assets }:

  • id — stable string identifier for the audit rule that fired (for example, alt-text). Treat the set as open; Knak may add new IDs over time. Callers that want to filter on specific rules should match against id; everyone else should ignore it.

  • message — human-readable description of the violation. Surface this directly to your end users.

  • assets — array of asset IDs the violation applies to.

See the response examples below for concrete payloads.

post/assets/{asset_id}/marketing-platform-syncs

Request

Path parameters

asset_idstring required

ID of the asset to sync.

Request body

integration_idstring required

ID of the target integration. Must belong to the authenticated company and have platform marketing_cloud.

sync_type'sync' | 'resync' required
template_namestring nullable

Optional override for the template/email name surfaced on the target platform. Falls back to the asset's name.

platform_parametersobject

Platform-specific sync configuration. Required when sync_type is sync. For marketing_cloud integrations, expects folder_id and email_asset_type.

skip_optimize_validationboolean

When true, bypasses the pre-sync audit validation and queues the sync even if the asset has audit errors or warnings. Requires the emails_bypass_optimize_sync permission on the authenticated user — callers without this permission will have the flag silently ignored (audit will still run). Use this to retry a sync after reviewing audit results that returned can_skip_optimize: true. Defaults to false.

Example request

{
  "integration_id": "609d7ce223def",
  "sync_type": "sync",
  "template_name": "Q2 Newsletter",
  "platform_parameters": {
    "folder_id": "123456",
    "email_asset_type": "htmlemail"
  }
}

Response

Accepted. Sync has been queued. When the pre-sync audit runs, the response includes meta.pre_sync_validation with any non-blocking warnings or asset exceptions. The block is omitted when audit was bypassed via skip_optimize_validation.

Example response

{
  "data": {
    "type": "marketing-platform-sync",
    "id": "609d7ce223411",
    "attributes": {
      "id": "609d7ce223411",
      "asset_id": "609d7ce223abc",
      "integration_id": "609d7ce223def",
      "platform": "marketing_cloud",
      "sync_type": "sync",
      "status": "pending",
      "platform_asset_id": "123456",
      "platform_asset_url": "https://mc.s7.exacttarget.com/emails/123456"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.