Send a transactional message via API with automatically created unique identifier

Question

I want to be able to do transactional single send (password reset) via an API using this endpoint https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/sendMessageSingleRecipient.htm. I managed to successfully send a test e-mail providing a unique messageKey, but in the future I want it to be a part of a larger solution and I would like to avoid handling the creation of unique ids on the side of the API using app.

Documentation says: "messageKey: Unique identifier of the definitionUnique identifier used to track message status. Can be automatically created when you create a message or provided as part of the request." Is it correct? How to trigger the automatic creation of the unique identifier? Using the endpoint without a messageKey value returns "MCMS_UTM_Validation_UnknownFieldName: Unrecognized email field name 'recipient'".

Answer 1

The documentation is slightly inaccurate here. The difference is found between these two pages:

https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/sendMessageSingleRecipient.htm

https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/sendMessageMultipleRecipients.htm

When using the "POST /messaging/v1/email/messages" endpoint, including a messageKey or not, in the endpoint URL, determines which version of the JSON body the endpoint will accept. The difference is:

• Including a messageKey means the endpoint will accept "recipient" (singular) as a parameter.
• Not including a message key means the endpoint will accept "recipients" (plural) as a parameter.

The documentation for sendMessageSingleRecipient says a messageKey "Can be automatically created when you create a message or provided as part of the request", which is not the case. Removing the messageKey from the URL and forming your request body like this, will allow you to send the request, and receive an autogenerated message key in the response:

{
  "definitionKey": "myEmail",
  "recipients": [
    {
      "contactKey": "1234",
      "to": "[email protected]",
      "attributes": {
      "attrib1": "foo",
      "attrib2": "bar",
      "attrib3": "42"
      }
    }
  ]
}

Response will look like this:

{
    "requestId": "287ab490-380b-4204-933b-1e6ff0227a82",
    "errorcode": 0,
    "responses": [
        {
            "messageKey": "HHhixHaj3kOvBplW8kWHsQ"
        }
    ]
}