Create an email asset via the API - Ortto Knowledge Base

Overview

Email asset creation via the API allows you to programmatically create new HTML email assets in Ortto. This is similar to creating an email asset using the Ortto Campaign Platform (MCP), but instead of using the user interface, you use a secure API request. This feature is designed for teams or integrations that need to automate the creation of email content directly from their systems or workflows.

This page provides descriptions of this endpoint:

Request resource and method
Valid parameters, headers, and request body values
The response payload

IMPORTANT: When creating email assets via the API, this will create a custom HTML email that cannot be edited in the Ortto editor.

HTTP method and request resources

Requests to create new HTML email assets in Ortto are submitted as a single POST method to the following URL:


 POST https://api.ap3api.com/v1/assets/create

NOTE: Ortto customers who have their instance region set to Australia or Europe will need to use specific service endpoints relative to the region:

Australia: https://api.au.ap3api.com/
Europe: https://api.eu.ap3api.com/

For example: https://api.eu.ap3api.com/v1/<entity/endpoint>

All other Ortto users will use the default service endpoint (https://api.ap3api.com/).

Path and query parameters

This endpoint takes no additional path and/or query parameters.

Headers

This endpoint requires a custom API key and content type (application/json for the request body) in the header of the request:

X-Api-Key: CUSTOM-PRIVATE-API-KEY
Content-Type: application/json

Request body

The request body consists of a JSON object with the valid elements listed in the table below. The following JSON object is an example of a request to create HTML email assets in your Ortto account’s CDP.

json
 {
  "name": "Q2 Newsletter - Product Update",
  "subject": "Here's what's new this quarter",
  "preview_text": "New features, customer stories, and upcoming events inside",
  "from_name": "Marketing Team",
  "from_email": "newsletter@yourcompany.com",
  "mail_html": "<html><body><h1>Q2 Product Update</h1><p>We've shipped some exciting new features this quarter. Read on to see what's new and how it can help your team.</p></body></html>",
  "track_utm": true,
  "track_reactions": true,
  "track_replies": false,
  "folder_id": "000000000000000000000000"
}

Valid request body elements:

Element	Description
`name`	This is the internal name you'll use in Ortto to identify this asset for filtering and reporting purposes. It is recommended to ensure that it is easy to uniquely identify.
`subject`	The subject line of the email, as it will appear to recipients in their inbox.
`preview_text`	The preview text (also known as preheader text) that displays next to or below the subject line in most inboxes. This can be used to give recipients extra context or a hook for the email content before they open it.
`from_name`	The sender name in the recipient's inbox.
`from_email`	The email address used to send the email. To use a custom domain, you'll need to ensure the custom domain is connected in your Ortto settings. Learn more about custom domains.
`mail_html`	This is the HTML body of your email. You must provide the full email content here, as email assets created via the API cannot be edited in Ortto's editor once created.
`track_utm`	If set to `true`, Ortto will automatically append UTM tracking parameters to the links in your email.
`track_reactions`	If set to `true`, Ortto will track emoji reactions left on the email by recipients. Learn more about adding reactions to a custom HTML email asset.
`track_replies`	If set to `true`, Ortto will track replies to the email as an activity. Set this to `false` if you do not want to capture reply data for this asset.
`folder_id`	This is the ID of the folder in your Ortto account where you want the asset to be saved. To find the `folder_id`, navigate to the folder in your Ortto account and it will be available in the URL.

Response payload

When a request is successful, the payload will return information about the created asset, including its ID, current state, and content used to create it.

json
 {
    "id": "000000000000000000000000",
    "name": "Q2 Newsletter - Product Update",
    "subject": "Here's what's new this quarter",
    "folder_id": "000000000000000000000000",
    "instance_id": "your-instance-id",
    "state": "draft",
    "type": "email",
    "campaign_type": "",
    "campaign_name": "",
    "should_duplicate": false,
    "created_at": "2026-09-25T16:48:01.291Z",
    "created_by_name": "api",
    "edited_at": "2026-09-25T16:48:01.291Z",
    "edited_by_name": "api",
    "draft": {
        "name": "Q2 Newsletter - Product Update",
        "subject": "Here's what's new this quarter",
        "preview_text": "New features, customer stories, and upcoming events inside",
        "from_name": "Marketing Team",
        "from_email": "newsletter@yourcompany.com",
        "reply_to": "",
        "cc": "",
        "bcc": "",
        "mail_html": "<html><head></head><body><h1>Q2 Product Update</h1><p>We've shipped some exciting new features this quarter. Read on to see what's new and how it can help your team.</p></body></html>",
        "mail_json": "",
        "track_utm": true,
        "links": null,
        "track_reactions": true,
        "custom_text": "",
        "track_replies": false,
        "disable_track_email_opens": false,
        "disable_track_link_clicks": false,
        "append_email_params": false,
        "asset_meta_version": 0,
        "asset_mail_version": 0,
        "supported_languages": null,
        "is_custom_html": true,
        "custom_html_filename": "custom.html",
        "has_public_audience": true,
        "edited_at": "2026-09-25T16:48:01.291Z",
        "edited_by_id": "000000000000000000000000",
        "edited_by_name": "api",
        "edited_by_email": "",
        "screenshot_url_task_id": "000000000000000000000000",
        "template": {
            "id": "000000000000000000000000",
            "name": "",
            "screenshot_url": "",
            "is_layout": false,
            "is_ap2_asset": false,
            "share_type": ""
        }
    },
    "shared_version": "",
    "shared_format": ""
}