This post is going to be about utilizing the REST API to both retrieve and edit/create Automation Notification emails inside of an Automation inside Automation Studio. This is, of course, undocumented, so it is use at your own risk – but it so far has been pretty stable and resilient.

If you are new to REST API and need some help, please check out this article I made about setting up POSTman to authenticate and then utilize it to make REST calls in SFMC. If you want to programmatically make this via SSJS instead, please see this article I made around options to use in SSJS to make REST API calls.

This article will have 3 different sections to help get you to the proper set up and usage on these notifications. We will look at:

• Bulk API retrieve to gather Automation IDs
• Retrieve Notifications via API
• Edit/Create Notifications via API

As you will note from the listed sections above, we will first need to gather Automation IDs. Now, the reason I specifically mention the Bulk retrieve API instead of say the documented ones is because the Automation ID we need is the encoded one that you can see in the URL in Automation Studio, or via this API.

Bulk Retrieve Automation REST API

You likely have seen this endpoint in many other places as it is super helpful, especially when trying to build a dashboard or overview of all the automations in a business unit. It returns every single automation in the account and does it really fast!

Once you have gone through the process of gathering an authentication token, you can make the following call to grab all the automations in the account:

GET /legacy/v1/beta/bulk/automations/automation/definition/
Host: {{TSE}}.rest.marketingcloudapis.com
Authorization: Bearer {{authToken}}
Content-Type: application/json

This will then return an object with an array in it containing all the automations. It should look something like this:

{
    "startIndex": 0,
    "itemsPerPage": 50,
    "totalResults": 12345,
    "entry": [
        {
            "id": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            "key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "createdDate": "2022-08-15T19:28:50.27Z",
            "name": "Automation1",
            ...
        },
        {
            "id": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            "key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "createdDate": "2019-12-17T22:26:41.29Z",
            "name": "Automation2",
            ...
        }
 
    ]
}

To help reduce clutter, I removed a good portion of the return that comes through as all we really need is the ID and the name/key to match it on. From there we can just sift through and find/filter/search through the array to gather the IDs we need for our notification updates.

Retrieve Notifications on Automations via REST API

Now that we have the encoded AutomationIDs, we can move on to the Retrieve endpoint to be able to pull in the existing notification settings. The reason we need to do this is that when you edit the Notifications via API, if you do not include the existing notifications, it will overwrite them and only include what you sent in your call. Plus it also gives us a template to work off of when we build our new additions

The call you will make is something like the below:

GET /legacy/v1/beta/automations/notifications/{{encodedAutoID}}
Host:{{tse}}.rest.marketingcloudapis.com
Content-Type: application/json
Authorization: Bearer {{authToken}}

Which will then return something like:

{
    "programId": "{{encodedAutoID}}",
    "workers": [
        {
            "programId": "{{encodedAutoID}}",
            "notificationType": "Complete",
            "definition": "[email protected]",
            "body": "",
            "channelType": "Account"
        },
        {
            "programId": "{{encodedAutoID}}",
            "notificationType": "Error",
            "definition": "[email protected]",
            "body": "",
            "channelType": "Account"
        }
    ]
}

The email addresses for each notification type (Error or Complete) are listed in the workers array. This is a near duplicate of what we will want to send back as the payload in the edit/create call.

Edit/Create Automation Notifications via REST API

You will want to notice that what is returned in the programID property in the payload from the GET no longer matches the encodedAutoID you used. This needs to be adjusted back to the encodedAutoID prior to submitting.

This property is in 2 places in the payload. At the top level in the object holding the workers array and also in each object in the workers array. So make sure to update each and every instance of this or it may return an error.

Now that we have our payload that is exact match to what is currently in there, how do we add to it? It is actually super simple. You just create a new object in the workers array. Like this:

{
    "programId": "{{encodedAutoID}}",
    "workers": [
        {
            "programId": "{{encodedAutoID}}",
            "notificationType": "Complete",
            "definition": "[email protected]",
            "body": "",
            "channelType": "Account"
        },
        {
            "programId": "{{encodedAutoID}}",
            "notificationType": "Complete",
            "definition": "[email protected]",
            "body": "",
            "channelType": "Account"
        },
        {
            "programId": "{{encodedAutoID}}",
            "notificationType": "Error",
            "definition": "[email protected]",
            "body": "",
            "channelType": "Account"
        }
    ]
}

You now have your payload all set to make the final call to update/create your notifications! Below is what the call should look like:

POST /legacy/v1/beta/automations/notifications/{{encodedAutoID}}
Host: {{TSE}}.rest.marketingcloudapis.com
Content-Type: application/json
Authorization: Bearer {{authToken}}

{
    "programId": "{{encodedAutoID}}",
    "workers": [
        {
            "programId": "{{encodedAutoID}}",
            "notificationType": "Complete",
            "definition": "[email protected]",
            "body": "",
            "channelType": "Account"
        },
        {
            "programId": "{{encodedAutoID}}",
            "notificationType": "Complete",
            "definition": "[email protected]",
            "body": "",
            "channelType": "Account"
        },
        {
            "programId": "{{encodedAutoID}}",
            "notificationType": "Error",
            "definition": "[email protected]",
            "body": "",
            "channelType": "Account"
        }
    ]
}

The return from this endpoint is completely empty if it is successful. So, if you get nothing but 200 status in return, then you were successful. Anything else likely means there was an error of some kind.

Now, I did mention this can be a programmatic solution and it can be…but with the multiple amount of API calls needed to update each individual Automation, it can be bulky and cumbersome. Depending on your need and the recurrence of the need, it may be easier to just do it inside the platform instead. I tend to love automating things as much as I can, so I wanted to share in case anyone else wanted to try it out!

As a final note, I urge you to check out my new series of articles on Leadership in Marketing Cloud! I am super proud of them and hope it helps current and future leaders in the SFMC community.