Complete Embed Flow

Before you start

Before your product can open the editor, make sure you have three things ready:

Requirement	What it means
Application and API credentials	Create an Application and API credentials in the Console. See Sign Up and Create an Application.
Backend service	Your backend stores API credentials, creates editor sessions, calls Editor plugin APIs, and receives saved content through the Push URL.
Frontend entry point	A button, link, page, or workflow where the End User starts creating or editing an email.

Base API URL:

https://api.aurorasendcloud.com/editor-plugin/

Default editor frontend URL:

https://abc.editor.aurorasendcloud.com/thirdApp

If your Application has a custom editor domain, replace https://abc.editor.aurorasendcloud.com with that domain. Keep /thirdApp and the query parameters unchanged.

⚠️
Security Requirement: To prevent credential exposure, your frontend must never call Aurora SendCloud APIs directly. Keep API credentials and the Application access token securely on your backend, passing only a short-lived, single-use editor code to the client browser.

Quick start embed path

Follow these five steps to run your first successful editor session.

Step 1: Create an Application access token

From your backend, authenticate the Application with HTTP Basic Auth. This endpoint has no request body and does not create an End User.

curl -X POST 'https://api.aurorasendcloud.com/editor-plugin/access/token' \
  -H 'Authorization: Basic ZGVtb19jbGllbnRfaWQ6ZGVtb19jbGllbnRfc2VjcmV0'

(The Basic Auth value is the Base64-encoded string of clientId:clientSecret.)

Response:

{
  "access_token": "example_access_token",
  "expires_in": 604800,
  "token_type": "Bearer"
}

Cache this Application-scoped token securely on your backend and request a new one before its expires_in period ends. The default lifetime is 604800 seconds (7 days).

Step 2: Create email

Create an email and use its id when opening the editor.

curl -X POST 'https://api.aurorasendcloud.com/editor-plugin/resource/email' \
  -H 'Authorization: Bearer example_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "user_12345",
    "name": "Welcome Email",
    "subject": "Welcome to Aurora SendCloud",
    "extra": {
      "source": "complete_embed_flow",
      "campaignId": "campaign_1001"
    }
  }'

Response:

{
  "id": "b7e4a9c2d1f60835",
  "name": "Welcome Email",
  "subject": "Welcome to Aurora SendCloud",
  "summary": "",
  "snapshot": null,
  "html": null,
  "settings": null,
  "extra": {
    "source": "complete_embed_flow",
    "campaignId": "campaign_1001"
  },
  "createTime": "2026-06-10T10:32:00Z",
  "updateTime": "2026-06-10T10:32:00Z"
}

Step 3: Generate one-time code

Request a one-time editor code for this editor session. The browser uses this code to open the editor.

curl -X POST 'https://api.aurorasendcloud.com/editor-plugin/access/code' \
  -H 'Authorization: Bearer example_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "user_12345",
    "name": "Jane Doe",
    "email": "[email protected]",
    "phone": "13800138000"
  }'

Response:

{
  "code": "example_code",
  "expires_in": 300,
  "userId": "user_12345"
}

This temporary code is single-use only and expires after 5 minutes.

Step 4: Open editor

Use the one-time code and email slug ID to open the editor in an iframe or a new window.

Use your active editor access domain. The default domain is:

https://abc.editor.aurorasendcloud.com

If your Application uses a custom editor domain, replace only the domain:

https://editor.yourcompany.com/thirdApp?code=example_code&id=b7e4a9c2d1f60835&lang=en_US

<iframe
  src="https://abc.editor.aurorasendcloud.com/thirdApp?code=example_code&id=b7e4a9c2d1f60835&lang=en_US"
  width="100%"
  height="700"
  frameborder="0"
  allow="clipboard-write"
></iframe>

Remember to request a fresh temporary code every time a user opens the editor.

Step 5: Receive Push URL callback

When the End User saves the email, the Editor plugin sends saved content to your configured Push URL.

Example payload after verification or decryption:

{
  "id": "b7e4a9c2d1f60835",
  "name": "Welcome Email",
  "userId": "user_12345",
  "subject": "Welcome to our platform",
  "summary": "A short introduction",
  "content": "<!DOCTYPE html><html>...</html>",
  "component": {},
  "snapshot": "https://cdn.example.com/snapshot.png",
  "extra": null,
  "createTime": "2026-07-16 10:00:00",
  "updateTime": "2026-07-16 10:15:00",
  "timestamp": 1784167200000
}

Your server should verify and decrypt the callback, store the returned content idempotently, then respond with an HTTP 200 OK status.

Full sequence diagram

sequenceDiagram
    autonumber
    participant EndUser as End User
    participant Frontend as Your Frontend
    participant Backend as Your Backend
    participant API as Editor plugin API
    participant Editor as Editor Frontend

    EndUser->>Frontend: Click Create Email or Edit Email
    Frontend->>Backend: Request editor session

    opt Application access token missing or expired
        Backend->>API: POST /access/token<br/>Application API credentials
        API-->>Backend: Application access token
    end

    alt Create a new email
        Backend->>API: POST /resource/email<br/>Bearer token + userId
        API-->>Backend: Email object with slug ID
    else Edit an existing email
        Backend->>Backend: Select existing email slug ID
    end

    Backend->>API: POST /access/code<br/>Bearer token + End User profile
    API-->>Backend: One-time code object

    Backend-->>Frontend: Editor URL with code + email slug ID
    Frontend->>Editor: Open /thirdApp?code=...&id=...&lang=...

    Note over Editor,API: Editor validates code and loads email internally

    EndUser->>Editor: Edit and save email
    Editor->>Backend: POST Push URL callback with saved content
    Backend->>Backend: Verify and store content
    Backend-->>Editor: HTTP 200

    opt Preview saved email
        Frontend->>Backend: Fetch saved content or preview
        Backend-->>Frontend: Saved email content or preview
    end

Frontend responsibilities

Your frontend should only:

Let the End User choose to create or edit an email.
Call your own backend to request an editor URL.
Open the returned editor URL in an iframe or a new window.
Optionally show save status or preview information after your backend receives the Push URL callback.

Your frontend should not:

Store or use API credentials.
Store or use the Application access token.
Call Editor plugin backend APIs directly.
Treat iframe or window state as the final saved email content.

Backend responsibilities

Your backend is responsible for the secure integration flow:

Store Application API credentials.
Cache and refresh the Application access token.
Use a stable userId from your own product when calling access and email APIs.
Create a new email or select an existing email slug ID.
Generate a new temporary code for every editor session.
Build and return the editor URL to your frontend.
Receive the Push URL callback.
Store the returned HTML and editor content.
Process duplicate or repeated saves safely.

Create vs edit

Use the create flow when the End User starts from a new email template:

Your frontend asks your backend to create a new editor session.
Your backend creates or reuses the Application access token.
Your backend calls POST /resource/email with the End User userId.
The Editor plugin returns a new email slug ID.
Your backend calls POST /access/code with the same userId.
Your frontend opens the editor with the code and new email slug ID.
The Editor plugin sends saved content to your Push URL when the End User saves.

Use the edit flow when the End User edits an existing email template:

Your frontend asks your backend to edit an existing template.
Your backend creates or reuses the Application access token.
Your backend selects the existing email slug ID for the End User.
Your backend calls POST /access/code with that End User's userId.
Your frontend opens the editor with the code and existing email slug ID.
The editor loads the existing email content.
The Editor plugin sends updated content to your Push URL when the End User saves.

Save and callback behavior

The Push URL is the source of saved email content.

When the End User saves, the Editor plugin sends saved content to your configured Push URL. Your backend should store the returned content, then return HTTP 200.

Do not rely on iframe state, browser state, or the Return URL to retrieve final HTML or editor data.

Configure the Push URL from:

Application -> Editor API -> Push URL

For callback payload, signature verification, idempotency, and testing guidance, see Push URL Callback.

Production checklist

Keep API credentials and the Application access token on your backend.
Generate a new temporary code every time the editor opens.
Use HTTPS for all API calls and Push URL callbacks.
Make the Push URL reachable from Editor plugin servers.
Verify Push URL callbacks before processing them.
Store saved content before returning HTTP 200.
Process repeated saves idempotently.
Keep your own mapping between your template record and the Editor plugin email slug ID.
Test both create and edit flows before production launch.

Before you start

Security Requirement: To prevent credential exposure, your frontend must never call Aurora SendCloud APIs directly. Keep API credentials and the Application access token securely on your backend, passing only a short-lived, single-use editor code to the client browser.

Quick start embed path

Step 1: Create an Application access token

Step 2: Create email

Step 3: Generate one-time code

Step 4: Open editor

Step 5: Receive Push URL callback

Full sequence diagram

Frontend responsibilities

Backend responsibilities

Create vs edit

Save and callback behavior

Production checklist