Get started

Discussions

Categories

Product Notice: Eloqua Application API 2.0 Email endpoints – “archive” property changing to “archive

JodyMooney-Oracle
JodyMooney-Oracle Group Product Manager, Oracle MarketingTorontoPosts: 321 Employee
edited Sep 10, 2020 4:27PM in Developer Tools

Overview

With the arrival of Eloqua release 20D (Nov 2020), the property, archive, that indicates if the email is archived, will be changed to archived for the Application API 2.0 Email endpoints, the Update an email endpoint will have new validation to prevent updating archived emails, and there will be changes to the Retrieve a list of emails endpoint. There will also be two new endpoints to archive and unarchive emails.

What’s changing?

With 20D, the property, archive, that indicates if the email is archived, will be changed to archived impacting the following endpoints:

Notes:

  • archived is returned at all depths: minimal, partial, and complete, when retrieving, updating, or creating an email
  • archived is returned as a string, with the only possible values being “true” or “false”
  • archived is a read-only property, and if including it when creating or updating an email it will be ignored
  • When creating a new email, whether via API or in Eloqua, the default for archived is “false”
  • Emails created prior to 20D, or any emails created prior to enabling this feature, will have archived set to “false”
  • Archiving / Unarchiving:
    • In Eloqua:
      • To archive an email, open the email, select File > Archive > Click Archive Asset
      • To unarchive an email, open the archived email, select File > Unarchive > Click Unarchive Asset
      • Via API:
        • To archive an email use the following endpoint: POST /api/REST/2.0/assets/email/{id}/archive
          • If asset is currently archived, a “304 NotModified” response will be returned
          • To unarchive an email use the following endpoint: POST /api/REST/2.0/assets/email/{id}/unarchive
            • If asset is currently unarchived, a “304 NotModified” response will be returned
  • If an email has archived set to “true”:
    • In Eloqua:
      • If the email is in an active campaign it will send as expected
      • The email cannot be added to campaigns, and cannot be sent from viewing the email (the batch send and email a contact options are not available in the actions drop-down)
      • The email will not appear in regular search or within Engage
      • Via API:
        • The email cannot be updated, and a validation error will be returned if attempting to update an archived email
        • The email will not be returned by default with the Retrieve a list of emails endpoint
  • Two new URL parameters are being introduced for the Retrieve a list of emails endpoint:
    • includeAvailable: Set to “true” to include unarchived emails. Set to “false” to not include unarchived emails. If not specified, the default is “true”.
    • includeArchived: Set to “true” to include archived emails. Set to “false” to not include archived emails. If not specified, the default is “false”.
  • Here is a summary of responses based on the new URL parameters includeAvailable and includeArchived for the Retrieve a list of emails endpoint:

includeAvailable

includeArchived

Response

true / null

false / null

Only unarchived

true / null

true

Both archived and unarchived

false

false / null

No emails

false

true

Only archived

  • When archiving or unarchiving an email a destination folder can be specified in the request body with the targetFolderId property
    • If unarchiving:
      • If target folder is archived, a “400 Validation” response will be returned, with details on the validation error in the body of the response
      • If archiving:
        • If target folder is not archived, a “400 Validation” response will be returned, with details on the validation error in the body of the response
  • These updates apply only to the 2.0 endpoints

Examples:

After 20D, archived is returned when retrieving emails at any depth instead of archive:

Request:

GET /api/REST/2.0/assets/email/10969?depth=minimal

Response: 200 OK

{

"type": "Email",

"currentStatus": "Draft",

"id": "10969",

"createdAt": "1599084894",

"createdBy": "71",

"depth": "minimal",

"folderId": "32874",

"name": "Email-archived-true",

"permissions": [

"Retrieve",

"SetSecurity",

"Delete",

"Update"

    ],

"updatedAt": "1599084894",

"updatedBy": "71",

    "archived": "true",

"htmlContent": {

"type": "StructuredHtmlContent",

"contentSource": "editor"

    }

}

Let’s unarchive the email we just retrieved, and move it into the unarchived folder id 3652:

Request:

POST /api/REST/2.0/assets/email/10969/unarchive

{

    "targetFolderId": "3652"

}

Response: 201 Created

{

    "type": "Email",

    "currentStatus": "Draft",

    "id": "10969",

    "createdAt": "1599084894",

    "createdBy": "71",

    "depth": "minimal",

    "folderId": "3652",

    "name": "Email-archived-true",

    "permissions": [

        "Retrieve",

        "SetSecurity",

        "Delete",

        "Update"

    ],

    "updatedAt": "1599084894",

    "updatedBy": "71",

    "archived": "false",

    "htmlContent": {

        "type": "StructuredHtmlContent",

        "contentSource": "editor"

    }

}

Let’s archive the email we just unarchived, and move it into the archived folder id 33037:

Request:

POST /api/REST/2.0/assets/email/10969/archive

{

    "targetFolderId": "33037"

}

Response: 201 Created

{

"type": "Email",

"currentStatus": "Draft",

"id": "10969",

"createdAt": "1599084894",

"createdBy": "71",

"depth": "minimal",

    "folderId": "33037",

"name": "Email-archived-true",

"permissions": [

"Retrieve",

"SetSecurity",

"Delete",

"Update"

    ],

"updatedAt": "1599084894",

"updatedBy": "71",

    "archived": "true",

"htmlContent": {

"type": "StructuredHtmlContent",

"contentSource": "editor"

    }

}

Let’s try to update the name using the Update an email endpoint to see the validation error:

Request:

PUT /api/REST/2.0/assets/email/10969

{

"id": "10969",

"name": "Email-archived-true-UPDATE"

}

Response: 400 Validation Error

[

    {

        "type": "ObjectValidationError",

        "container": {

            "type": "ObjectKey",

            "objectId": "10969",

            "objectType": "Email"

        },

        "property": "Archived",

        "requirement": {

            "type": "StatusRequirement",

"allowedStatusForOperation": "False"

        },

        "value": "True"

    }

]

Let’s try archiving this email to see the “304 NotModified” response:

Request:

POST /api/REST/2.0/assets/email/10969/archive

Response: 304 NotModified

Let’s try unarchiving this email with a folder that’s archived to see the validation response:

Request:

POST /api/REST/2.0/assets/email/10969/unarchive

{

    "targetFolderId": "33037"

}

Response: 400 Validation Error

[

    {

        "type": "ObjectValidationError",

        "container": {

            "type": "ObjectKey",

            "objectId": "33037",

            "objectType": "Folder"

        },

        "property": "archive",

        "requirement": {

            "type": "StatusRequirement",

"allowedStatusForOperation": "False"

        },

        "value": "True"

    }

]

Retrieving only unarchived emails with the Retrieve a list of emails endpoint will be the default when not including any URL parameters:

Request:

GET /api/REST/2.0/assets/emails

Retrieving both archived and unarchived emails with the Retrieve a list of emails endpoint:

Request:

GET /api/REST/2.0/assets/emails?includeArchived=true

Retrieving only archived emails with the Retrieve a list of emails endpoint:

Request:

GET /api/REST/2.0/assets/emails?includeArchived=true&includeAvailable=false

Timeline

With the arrival of Eloqua release 20D (Nov 2020), the property, archive, that indicates if the email is archived, will be changed to archived for the Application API 2.0 Email endpoints, the Update an email endpoint will have new validation to prevent updating archived emails, and there will be changes to the Retrieve a list of emails endpoint. There will also be two new endpoints to archive and unarchive emails. Check the Eloqua Release Center for specific dates and times.

Next Steps

If retrieving, updating, or creating emails via the Application API, prepare for the archive property to be changed to archived and returned at all depths, for the Update an email endpoints will have new validation to prevent updating archived emails, and for the Retrieve a list of emails endpoint to only return unarchived emails by default.

Prepare for the following responses based on the new URL parameters includeAvailable and includeArchived for the Retrieve a list of emails endpoint:

includeAvailable

includeArchived

Response

true / null

false / null

Only non-archived

true / null

true

Both archived and non-archived

false

false / null

No emails

false

true

Only archived

If requiring the ability to programmatically archive or unarchive emails, note the addition of these two endpoints:

  • POST /api/REST/2.0/assets/email/{id}/archive
  • POST /api/REST/2.0/assets/email/{id}/unarchive

Additional Resources

View changes for Eloqua's APIs including, new features, significant recent changes, and platform notices, on the Eloqua Developer Changelog.

If you have questions, post a discussion on Code It!

FAQ

Q: What endpoints are impacted by this change?

A: The following endpoints are impacted:

Q: What will happen if an email in an active campaign is archived?

A: Archived emails in an active campaign will send as expected.

Group Product Manager, CX - Marketing: Eloqua

Tagged:
· Share on FacebookShare on Twitter