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 ContentUpdate Email Content SectionApprove Email Draft.  The call will return a 709 error code, and the corresponding error message.

 

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 NameGet 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, 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.

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.

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.

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.