Assets

Marketo provides APIs to interact with most marketing and organizational assets within Marketo.

Assets

Marketo assets include:

  • Folders
  • Programs
  • Emails
  • Email Templates
  • Landing Pages
  • Landing Page Templates
  • Snippets
  • Forms
  • Tokens
  • Files

API

For a full listing of Asset API endpoints, including parameters and modeling information, see the Asset API Endpoint Reference.

Query

Assets typically have three patterns by which they can be retrieved: by id, by name, and by browsing.  By id and by name will both retrieve a single asset for a given parameter, while browsing will return and allow paging through the whole list of assets of that type.  Individual types of assets have varying parameters by which they can be filtered, so be sure to look at their individual documents for specifics.

In certain cases the browse endpoint for some asset types will not return child assets, such as the allowable values for a tag, and they must be retrieved individually using either the By Name or By Id endpoint to return the complete set of metadata.  Others may have separate endpoints entirely for retrieving dependent objects like Form Fields.

By Id

By Name

Note: For technical reasons, the Asset APIs are unable to search for Asset names containing commas (,).  It is recommended that your naming convention exclude commas for all asset types.

Browse

Browsing through assets will always permit two query parameters:

  • offset – An integer offset to return results from.
  • maxReturn – Limits the number of records returned.  Defaults to 20 if unset, and has a maximum of 200.

Create and Update

For simple asset types like Folders, Tokens and Files there is typically only a single endpoint for creation, and then an additional endpoint for updating records by ID.  Assets are created with a name which is always required, and then any metadata and IDs are returned by the create or update response.

For example, here’s how to create a token:

To update a folder you would do this:

Other assets have more complex structures and require updates to additional subsections or child objects, and then ultimately have to undergo approval before they can be put into use.  These asset types include Forms, Emails, Email Templates, Landing Pages, and Landing Page templates.  These will each have a single endpoint for creating a record, then additional endpoints for updating metadata, content, and content sections.

For example, to create a Landing Page, you’ll need to call its create endpoint with a template ID and then retrieve its content sections, and update each one individually to add content, before approving it so that it can be deployed live.

Complex Create

Landing pages first require creating a Landing Page asset using a parent template.  This creates a new landing page containing the default content of the template for each content section.

Get Sections

To populate the content for a landing page, you need to retrieve the list of content sections, and then perform individual updates for any section that deviates from the template.

Update Section

Approval

Many asset types have an associated draft and approval system, including Emails, Landing Pages, Snippets, Forms, and their corresponding templates.  Trying to approve an asset will evaluate it against a specific set of validation rules, and then either set it to an approved state, or return a failure reason.  For these types of assets, whenever an update is made to the content of a particular asset the changes are made to a draft of the asset, which does not affect the approved version.  This allows changes to content to be safely made without affecting live versions of the asset.  The changes can then be applied to the live version by using the approval endpoint.  This also clears the draft state of the asset until any additional updates are applied.

The successful approval replaces the previous live version with the updated version.

Discarding drafts is also available through an endpoint for each valid asset type.  Using this on an asset which is in an approved with draft state will discard the current draft and any pending changes it has.  Using this on an asset that currently has no approved version will do nothing and return an error.  Draft-only assets may be deleted, but they may not be discarded.

Assets can also be unapproved if they are in an approved-only state.  This will take down any live versions of the asset and returning the asset to a draft-only state while also discarding any associated draft.  This action can only be performed on most assets if it is not in use anywhere in Marketo, such as an email being referred to in a Send Email flow step, or a snippet being embedded in an Email.

Delete

Assets with approval and draft states, except for forms, may not be deleted while approved, and must be unapproved prior to deletion.  Deletions generally can only be performed when an asset is unapproved and out of use and in the case of folders, being empty of assets.  One notable exception are programs, which can be deleted along with all of their child contents, so long as the program and its contents are not in use anywhere outside of the bounds of the program.

Timeouts

Asset APIs have a timeout of 300s