Email 2.0 and Email API FAQ's

Version 4

     

     

    What is the Email API?

    API stands for Application Programming Interface and the Email API allows an automated process to create and edit emails in Marketo. There are also other API calls that involve emails, such as Approve Snippet (assuming the Snippet is used in an Email) and Clone Program (assuming the Program contains Emails). There are also API calls to create and update Email Templates. Essentially, the API can do many things that you can also do through the Marketo user interface, but then in an automated fashion.

     

    What is the Email API used for?

    There are many scenarios: an external system could create Emails in Marketo using data that lives outside of Marketo. A translation service provider could clone a master Email, translate it to many languages, then save them back into Marketo as localized Emails. A reporting system could extract Emails from Marketo to use in reports that are generated outside of Marketo. An external system could Clone a Program that contains Emails, then populate the Program Tokens and schedule the Email to be sent out at a specific time. There could be an external email template creation system that creates new Email templates in Marketo through the API.

     

    What is Email 2.0?

    “Email Experience 2.0” is the new Marketo product feature with the enhanced email editor, documented here: https://docs.marketo.com/display/public/DOCS/Email+Editor+v2.0+Overview. It can be switched on in Admin > Email > Edit Email Editor Settings. All Emails and Email Templates also have a version number, either 1.0 (the old version) or 2.0 (the new version). If we refer to “Email 2.0 asset” we mean an email or email template in the new upgraded 2.0 format.

     

    Does the Email API Work on Email 2.0 Assets?

    Right now, the Email API cannot be used on Emails 2.0 assets. That means that the API cannot create, edit or approve Emails and Email Templates in the Email 2.0 format. Also, the API cannot approve Snippets that are used in Email 2.0 assets and it cannot clone Programs that contain Email 2.0 assets.

     

    Will the Email API Break when Enabling Email Experience 2.0?

    No. Enabling Email 2.0 will not automatically upgrade Emails or Email Templates to the new 2.0 format, so existing 1.0 Emails and Email Templates can still be manipulated with the Email API. Also, the Email API can still create new Emails and Email Templates in the 1.0 format.

    However – after enabling Email 2.0 – any Email or Email Template that is created or edited and approved through the Marketo User Interface will automatically be upgraded to the 2.0 format, thereby making it inaccessible to the Email API.

     

    Should I Upgrade to Email 2.0 Experience?

    It depends on your specific API workflow. If an Email is only touched by the API and not by human editors, you should be safe to upgrade to the Email 2.0 Experience. Just make sure all end users know they should not touch certain assets.

    If your workflow involves editing the same Email asset via human editing steps first and then via the Email API, then it is better to delay your upgrade to the Email 2.0 Experience until the Email APIs are made compatible with the 2.0 format, because human editing will make the asset inaccessible for the Email API. This may include translation workflows from LaunchPoint partners.

    If in doubt, please contact Marketo or your LaunchPoint partner for advice.

     

    When Will the Email API be Compatible with Email 2.0 Assets?

    A future Marketo release will add support for Email 2.0 Assets in the Email APIs. Exact timing is still to be confirmed, but it will be in 2016.

     

     

    How Are 1.0 Assets Upgraded to 2.0 Assets?

    If you edit an “Approved" or “Approved with Draft” 1.0 Email with Email 2.0 enabled, the draft is converted to the 2.0 format. You can still discard the draft to go back to the approved 1.0 format. Once you approve the email and it becomes 2.0, the Email cannot be converted back to 1.0. If you edit a “Draft” 1.0 Email (never been approved), this will automatically be converted to 2.0 with no option to revert back to the 1.0 format. The same applies to Email Templates.

     

     

    What to Do When an Email Was Accidentally Converted to Email 2.0 format?

    If an Email or Email Template was accidentally converted to the 2.0 format, you’d have to copy the asset contents to a text editor, disable Email 2.0, then create a new 1.0 asset using the content that you copied.

     

    What Specific API Calls Don’t Work on Email 2.0 Assets?

    These API calls are not compatible with Email 2.0:

    • Email

      • Create Email

      • Get Email by Id

      • Delete Email by Id

      • Update Email

      • Get Emails

      • Get Email Content by Id

      • Update Email Content by Id

      • Update Email Content by Editable Section

      • Get Email Dynamic Content by Id

      • Update Email Dynamic Content by Id

      • Approve Email by Id

      • Unapprove Email by Id

      • Discard Email Draft by Id

      • Clone Email

      • Get Email by Name

      • Send Sample Email

    • Email Template

      • Create Email Template

      • Get Email Template by Id

      • Get Email Template by Name

      • Update Email Template

      • Delete Email Template by Id

      • Get Email Templates

      • Get Email Template Content by Id

      • Update Email Template Content by Id

      • Approve Email Template by Id

      • Unapprove Email Template by Id

      • Discard Email Template Draft by Id

      • Clone Email Template

    • Program

      • Clone Program

        • Only when you clone a Program that contains Email 2.0 assets

    • Campaign

      • Schedule Campaign with the cloneToProgramName parameter

        • Only when you clone a Program that contains Email 2.0 assets

     

     

    What Error Will the API Return for Email 2.0 Assets?

    If you try to update an Email 2.0 Asset with the API, this is the error message you’ll receive:

     

    "errors": [

      {

        "code": "709",

    "message": "API currently does not support operations on emails created or edited using editor version 2.0."

      }

     

    Email 2.0 API Error.png

     

    The error code is a “709” error. For detailed information about API error codes, check out the developer’s page that defines them all here: http://developers.marketo.com/documentation/rest/error-codes/