Complete Embed Flow

Use this page to understand what to prepare, which system calls which endpoint, what the Editor plugin returns, and how saved email content comes back to your product.

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 you configure a custom editor domain in Domain, replace https://abc.editor.aurorasendcloud.com with your custom domain. Keep /thirdApp and the query parameters unchanged.

⚠️
Security Requirement: To prevent credential exposure, your frontend must never call Aurora SendCloud APIs directly. Keep all API credentials and End-User tokens securely on your backend, passing only short-lived, single-use access codes to the client browser.

Quick Start Embed Path

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

Step 1: Create or refresh an End-User Token

From your backend, request an access token for the active user who needs to open the editor.

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

(Note: The Basic Auth value is the Base64-encoded string of client_id:client_secret)

Response:

{
  "success": true,
  "code": 200,
  "message": "user login success",
  "data": {
    "id": "user_12345",
    "name": "Jane Doe",
    "email": "[email protected]",
    "phone": "",
    "token": "example_access_token",
    "createTime": "2026-06-10 10:30:00",
    "expireTime": "2026-06-17 10:30:00"
  }
}

Cache this token securely on your backend and refresh it prior to its expireTime.

Step 2: Create email

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

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

Response:

{
  "success": true,
  "code": 200,
  "message": "create email success",
  "data": {
    "id": "123",
    "name": "Welcome Email",
    "extra": "{\"source\":\"complete_embed_flow\",\"campaignId\":\"campaign_1001\"}",
    "createTime": "2026-06-10 10:32:00"
  }
}

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"

Response:

{
  "success": true,
  "code": 200,
  "message": "obtained code success",
  "data": "example_code"
}

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

Step 4: Open editor

Use the one-time code and email 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 domain configured in Domain, replace only the domain:

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

<iframe
  src="https://abc.editor.aurorasendcloud.com/thirdApp?code=example_code&id=123&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:

{
  "emailId": "123",
  "userId": "user_12345",
  "subject": "Welcome to our platform",
  "html": "<!DOCTYPE html><html>...</html>",
  "json": {
    "body": {
      "rows": []
    }
  },
  "timestamp": 1798713000
}

Your server should securely store both the raw HTML and the layout JSON, 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 End User token missing or expired
        Backend->>API: POST /access/token<br/>Application API credentials
        API-->>Backend: End User token
    end

    alt Create a new email
        Backend->>API: POST /access/email<br/>Bearer End User token
        API-->>Backend: Email ID
    else Edit an existing email
        Backend->>Backend: Select existing email ID
    end

    Backend->>API: POST /access/code<br/>Bearer End User token
    API-->>Backend: Temporary code

    Backend-->>Frontend: Editor URL with code + email 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 End User 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.
Map your product user to an Editor plugin End User ID.
Create or refresh the End User token.
Create a new email or select an existing email 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 refreshes the End User token.
Your backend calls POST /access/email.
The Editor plugin returns a new email ID.
Your backend generates a temporary code.
Your frontend opens the editor with the code and new email 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 refreshes the End User token.
Your backend selects the existing email ID.
Your backend generates a new temporary code.
Your frontend opens the editor with the code and existing email 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 End User tokens 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 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 all API credentials and End-User tokens securely on your backend, passing only short-lived, single-use access codes to the client browser.

Quick Start Embed Path

Step 1: Create or refresh an End-User 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