Eloqua Application API Email endpoints – depth and search URL parameter changes (Aug 2019)

Version 1

    Overview

     

    With the arrival of Eloqua release 19C (Aug 2019), we are modifying the Application API Email endpoints, so that minimal depth will return subject. Additionally, with 19C, using the search URL parameter with name when retrieving a list of emails, will return matches for name and subject.

     

    What’s changing?

     

    With 19C, the change to minimal depth to include subject, will impact the following endpoints:

     

    With 19C, the change to the search URL parameter with name to include matches for name and subject will impact the following endpoints:

     

    Notes:

    • When using the search URL parameter, if a term, the field or property to search on, is not indicated, then the search is based on name, so the following two searches are exactly the same:
      • ?search=name=test
      • ?search=test
    • This update applies to both 1.0 and 2.0; however, all examples are using the Email 2.0 endpoints, and it’s recommended to use 2.0, as some features are only available on 2.0

     

    Examples – subject returned at minimal depth

     

    After 19C, subject is returned when retrieving Emails at minimal depth:

     

    Request:

     

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

     

    Response: 200 OK

     

    {

        "type": "Email",

        "currentStatus": "Draft",

        "id": "9595",

        "createdAt": "1561402509",

        "createdBy": "71",

        "depth": "minimal",

        "folderId": "42",

        "name": "19C_subject_minimal",

        "permissions": [

            "Retrieve",

            "SetSecurity",

            "Delete",

            "Update"

        ],

        "updatedAt": "1561402584",

        "updatedBy": "71",

        "archive": "false",

        "htmlContent": {

            "type": "RawHtmlContent",

            "contentSource": "upload"

        },

        "subject": "Email Subject Line"

    }

     

    Examples – search URL parameter with name will include matches for name and subject

     

    The following emails are created in Eloqua:

    • id: 9597
      • name: search_name_and_subject
      • subject: Subject Line
    • id: 9598
      • name: Email_Name
      • subject: search_name_and_subject

     

    Before 19C, using the search URL parameter with name will only match on name:

     

    Request:

     

    GET /api/REST/2.0/assets/emails?search=name=search_name_and_subject

     

    OR

     

    GET /api/REST/2.0/assets/emails?search=search_name_and_subject

     

    Response:

     

    {

        "elements": [

            {

                "type": "Email",

                "currentStatus": "Draft",

                "id": "9597",

                "createdAt": "1561417565",

                "createdBy": "71",

                "depth": "minimal",

                "folderId": "42",

                "name": "search_name_and_subject",

                "permissions": [

                    "Retrieve",

                    "SetSecurity",

                    "Delete",

                    "Update"

                ],

                "updatedAt": "1561417565",

                "updatedBy": "71",

                "archive": "false",

                "htmlContent": {

                    "type": "RawHtmlContent",

                    "contentSource": "upload"

                },

                "subject": "Subject Line"

            }

        ],

        "page": 1,

        "pageSize": 1000,

        "total": 1

    }

     

    After 19C, using the search URL parameter with name will include matches for name and subject:

     

    Request:

     

    GET /api/REST/2.0/assets/emails?search=name=search_name_and_subject

     

    OR

     

    GET /api/REST/2.0/assets/emails?search=search_name_and_subject

     

    Response:

     

    {

        "elements": [

            {

                "type": "Email",

                "currentStatus": "Draft",

                "id": "9597",

                "createdAt": "1561417565",

                "createdBy": "71",

                "depth": "minimal",

                "folderId": "42",

                "name": "search_name_and_subject",

                "permissions": [

                    "Retrieve",

                    "SetSecurity",

                    "Delete",

                    "Update"

                ],

                "updatedAt": "1561417565",

                "updatedBy": "71",

                "archive": "false",

                "htmlContent": {

                    "type": "RawHtmlContent",

                    "contentSource": "upload"

                },

                "subject": "Subject Line"

            },

            {

                "type": "Email",

                "currentStatus": "Draft",

                "id": "9598",

                "createdAt": "1561417604",

                "createdBy": "71",

                "depth": "minimal",

                "folderId": "42",

                "name": "Email_Name",

                "permissions": [

                    "Retrieve",

                    "SetSecurity",

                    "Delete",

                    "Update"

                ],

                "updatedAt": "1561417604",

                "updatedBy": "71",

                "archive": "false",

                "htmlContent": {

                    "type": "RawHtmlContent",

                    "contentSource": "upload"

                },

                "subject": "search_name_and_subject"

            }

        ],

        "page": 1,

        "pageSize": 1000,

        "total": 2

    }

     

    Timeline

     

    With the arrival of Eloqua release 19C (Aug 2019), we are modifying the Application API Email endpoints, so that minimal depth will return subject. Additionally, with 19C, using the search URL parameter with name when retrieving a list of emails, will return matches for name and subject. Check the Eloqua Release Center for specific dates and times.

     

    Next Steps

     

    subject returned at minimal depth

     

    If retrieving emails at minimal depth, prepare for subject to be returned at this depth. If you are using partial or complete depth specifically to retrieve subject, these API calls should be updated to return minimal depth in order to take advantage of a more efficient request.

     

    Using the search URL parameter with name will include matches for name and subject

     

    If using the search URL parameter to filter a list of emails by name, prepare for these requests to include matches for name and subject, instead of matches for just name.

     

    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 change to minimal depth to include subject, will impact the following endpoints:

     

    The change to the search URL parameter with name to include matches for name and subject will impact the following endpoints:

     

    Q: Why are these changes being made?

    A: subject is commonly queried value on emails, so the ability to search by subject, and also retrieve subject at minimal depth is useful for many use cases.