Emails

Email Endpoint Reference
A full set of REST endpoints are provided for manipulating email assets.

Note: If you are using Marketo Predictive Content, the following endpoints will fail if they reference an email that contains predictive content: Get Email Content, Update Email Content Section, Approve Email Draft.  The call will return a 709 error code, and the corresponding error message.

 

Note: As part of the Email Editor 1.0 Deprecation, 1.0 Email Assets will become read-only at the end of 2019.  All 1.0 Email Assets must be converted to 2.0 as described here.  To help developers prepare for that event, we have added warnings to all Email-related endpoints that attempt to modify 1.0 Email Assets.

 

Contents
  1. Query
    1. By Id
    2. By Name
    3. Browse
  2. Query Content
  3. Query CC Fields
  4. Create and Update
    1. Content Section, Type, and Update
    2. Update Editable Section
  5. Modules
    1. Query
    2. Add
    3. Delete
    4. Duplicate
    5. Rearrange
    6. Rename
  6. Variables
    1. Query
    2. Update
  7. Approval
    1. Approve
    2. Unapprove
    3. Discard
    4. Delete
  8. Clone
  9. Send Sample
  10. Preview Email
  11. Replace HTML

Query

The query pattern for emails is identical to that of templates, allowing queries by id, by name, and browsing, and for filtering based on folder with the browse and by name APIs.

Note: If an email is part of a program that is using  Email Testing (A/B Test, or Champion/Challenger Test), then that email is not available for query using the following endpoints: Get Email by Id, Get Email by Name,  Get Emails.  The call will indicate success, but will contain the following warning: “No assets found for the given search criteria.”

By ID

By Name

For by name, you can optionally pass a folder to search only in that folder.

Browse

Browsing folders works like other Asset API browse endpoints, and allows optional filtering on status, folder, earliestUpdatedAt/latestUpdatedAt, maxReturn, and offset.  status can be either Approved or Draft.  folder is a  JSON object containing id and type.  maxReturn  is a integer that limits the number of results (default is 20, maximum is 200), and offset is an integer that can be used with maxReturn to read through large result sets (default is 0).

Query Content

You can retrieve the available editable sections for an email by querying its content, and optionally filter on status to get the sections for either the Approved or Draft versions.

Sections may return as having a type of dynamicContent.  See the Dynamic Content section for more info.

Query CC Fields

You can retrieve the set of fields enabled for Email CC in the target instance by calling the Get Email CC Fields endpoint.

Create and Update

Emails are created based from a source template, and have a list of editable sections derived from each separate HTML element in that template with a class of “mktEditable” and a unique id property.  Creating an email with the API creates a record based on the template along with any additional metadata passed.  The following parameters are required for a successful Create Email call: name, template, folder.

The following parameters are optional for creation: subject, fromName, fromEmail, replyEmail, operational.  If unset, subject will be empty, fromName, fromEmail and replyEmail will be set to instance defaults, and operational will be false.

Updating an email record can be done by id.  This allows for updating the description or name of the email.

Content Section, Type, and Update

The content for each section of an email must be updated individually, apart from the subject, fromName, fromEmail, and replyEmail, which are updated using the Update Email Content endpoint.  When using this endpoint, these values can also be set to use dynamic content instead of static content.  Each parameter is a type/value JSON object, where type is either “Text” or “DynamicContent” and value is either the appropriate text value, or the id of the segmentation to use for the dynamic content.  Data is passed as POST x-www-form-urlencoded, not as JSON.

If setting a section to use dynamic content, the section ID will need to be retrieved via the Get Email Content call.

Update Editable Section

Editable sections are updated by their individual htmlIds.  Only the id of the email and htmlId of the section are required as path parameters, while type, value, and textValue are optional.  Type may be one of “Text,” “DynamicContent,” or “Snippet” and will affect what is passed in the value.  If the type is Text, then the value is a string containing the HTML content of the section.  If it is DynamicContent, then it is a JSON block, with three members, type, which will be “DynamicContent”, segmentation which is the id of the segmentation to use for the content, and default, which is a string containing the default HTML content of the section.  The optional textValue parameter is a string containing the text version of the section.  Data is passed as POST x-www-form-urlencoded, not as JSON.

Note: If autocopy to text is disabled for a snippet embedded in an email, then the HTML value of the snippet is updated, and then the text version of another section in the email is updated, then the text version of the email will have have text reflecting the updated value of the snippet HTML, not the previous version as would be expected with autocopy disabled.

Modules

In Email Editor 2.0, a module is a section of your email that is defined in the template.  Modules may contain any combination of elements, variables, and other HTML content as described here.  Marketo offers a set of APIs for managing modules within an email.  For module-related endpoints that require the HTTP POST method, the body is formatted as “application/x-www-form-urlencoded” (not as JSON).

Most of the module-related endpoints require a “moduleId” as a path parameter.  This is a string that describes the module.  moduleIds are returned by Get Email Content endpoint as the “htmlId” attribute (see Query section below).

Query

To work with modules, you must specify a moduleId parameter, which uniquely identifies the module.  You may also need to specify the module index parameter, which is an integer that describes the order of the module in the email.

Retrieve moduleIds and their indexes by specifying the email id as a path parameter.

The following example queries a 2.0 email based on the “Skeleton” template found in “Starter Templates” section of the Template Picker UI.

The result array contains elements that describe both modules and HTML elements intermixed.  Module elements contain a “contentType”: “Module” attribute, and an “index” attribute.  The moduleId is stored in the “htmlId” attribute.

Continuing with the “Skeleton” example above, the following table contains a summary of moduleIds and their corresponding indexes contained in the email.

moduleId (a.k.a. htmlId) Index
spacer 0
free-image 1
video 2
free-text 3
CTA 4
hr 5
two-articles 6
footer 7

Add

Add a module to an email by selecting from one of the existing modules contained in the email template that is in use.  Do this by specifying the email id, and the moduleId as path parameters.  The index query parameter is required and determines the order of the module in the email.  If the index value exceeds the largest existing index value, then the module is appended to the email.

Delete

Delete a module by specifying the email id, and the moduleId as path parameters.

Duplicate

Duplicate a module by specifying the email id, and the moduleId as path parameters.  This call will duplicate the module, placing it underneath the original module and pushing the other modules down.

Rearrange

Rearrange modules by passing them in the desired order via the positions parameter.  The positions parameter is a JSON array that contains all modules and the desired postition within the email for each.  Each array element contains a JSON object of the following form:  { “index”: <index>, “moduleId”: “<moduleId>” }, where <index> is the zero-based module order number, and <moduleId> is the moduleId.

Rename

Rename a module on an email by passing the new name via the name parameter.  Specify the email id, and the moduleId (existing name) as path parameters.

Variables

In Email Editor 2.0, variables are used to store values for elements in your email.  Each variable is defined by adding Marketo-specific syntax to your HTML as described here.  Marketo offers a set of APIs for managing variables within an email.

Query

Retrieve variables for an email by specifying the email id as a path parameter.

The following example queries a 2.0 email based on the “Skeleton” template found in “Starter Templates” section of the Template Picker UI.

The result array contains elements describing variables, one variable per element.

Variables can be scoped globally to the entire email, or locally to a specific module.  Variables of either scope contain “name”, “value”, and “moduleScope” attributes.  The “moduleScope” attribute is boolean, where false indicates global and true indicates local.  Local variables contain an additional “moduleId” attribute that specifies the module that the variable is associated with.

Update

Update a variable in an email by passing the new desired value via the value parameter.  Specify the email id, and the variable name as path parameters.  If you are updating a module variable, then you must also pass the moduleId parameter to specify the module that the variable is associated with.

In the following example we update a global variable named “hrBorderSize” to a value of 2.

In the following example we update a local variable named “ctaLinkText” to a value of “Click this button!” in moduleId “CTA”.

Approval

Emails follow the standard pattern for approvals of asset records.  You can approve a draft, unapprove an approved version, and discard an existing draft of an email through each of their own endpoints.

Approve

When calling the approval endpoint, the email will be validated against the rules for Marketo emails. The from name, from email, reply to email, and subject have to be populated before the email can be approved.

Unapprove

The unapprove operation can only be performed on approved emails.

Discard

The email must be in draft status to be discarded.  An approved email cannot be discarded.

Delete

Clone

Marketo provides a simple method for cloning an Email.  This type of request is made with an application/x-www-url-urlencoded POST, and takes two required parameters, name, and folder, an embedded JSON object with id and type.  description is also an optional parameter.  If no approved version exists, then the draft version will be cloned.

Send Sample

You can trigger a sample email via the api, to be sent to the emailAddress query parameter.  You can also optionally add a leadId parameter to impersonate a particular lead from your database, and a textOnly parameter to send only the text version of the email.

Preview Email

Marketo provides the Get Email Full Content endpoint to retrieve a live preview of an email as it would be sent to a recipient.  This endpoint can only be used on Version 2.0 Emails.  There is one required parameter, the id path parameter which is the id of the email asset you wish to preview.  There are three additional optional query parameters:

  • status: Accepts the values “draft” or “approved” which will default to the approved version, if approved, draft if unapproved
  • type: Accepts “Text” or “HTML” and defaults to HTML
  • leadId:  Accepts the integer id of a lead.  When set, previews the email as though it were received by the designated lead

Replace HTML

Marketo provides the Update Email Full Content endpoint to replace the entire contents of an email asset.  This endpoint can only be used on Version 2.0 Emails which have had the UI “Edit Code” function used on them, and have had the relationship to their parent template broken.  This API is primarily intended for use on assets that have been cloned as part of a program, and cannot be modified with the standard content endpoints.  Note that emails with dynamic content are not supported.  Also, if you try to replace HTML on an email where the relationship is intact, then an error is returned.

This endpoint expects a Content-Type : multipart/form-data with the id parameter in the path, the id of the email, and one parameter in the body, content as a complete HTML email document with the Content-Type “text/html.”  A malformed HTML document will emit a warning, but may not subsequently permit approval, while inclusion of JavaScript and/or <script> tags in the document will cause the call to fail and emit an error.