PATCH /messaging/v1/sms/definitions/{definitionKey}

Overview

Updates a specific message definition. It can take up to two minutes for outbound messages to reflect the changes.

URL Parameters

Name	Type		Description
definitionKey	string	Required	Unique identifier of the definition.

JSON Parameters

Name	Type		Description
name	string	Required	Name of the definition. Must be unique.
content.message	string	Required	The message content that you want sent with each message. Use substitution strings and AMPscript to personalize the message.
status	string		Operational state of the definition: active, inactive, or deleted. A message sent to an active definition is processed and delivered. A message sent to an inactive definition isn’t processed or delivered. Instead, the message is queued for later processing for up to three days.
description	string		User-provided description of the send definition.
subscriptions.shortCode	string	Required	The short or long code for the mobile transmissions for each message on this definition.
subscriptions.countryCode	string		The country code associated with the shortCode for the mobile transmissions for each message on this definition. Don't use for long codes, unless your account configuration requires it.
subscriptions.keyword	string		The keyword used to track messages
subscriptions.autoAddSubscriber	boolean		Permits adding a recipient as subscriber against the shortCode using contactKey. When false, the message is rejected if contactKey doesn't exist as a subscriber. Default is true.
options.urlShortenerOptions.IsLinkShorteningEnabled	boolean		Indicates if URL shortening is enabled for URLs in the message body. The values are `true` and `false`. Default is `false`.
options.urlShortenerOptions.isSubscriberTrackingEnabled	boolean		Indicates if subscriber level tracking is enabled for URLs in the message body. The values are `true` and `false`. Default is `false`. The value is `true` if the value of shortenerType is `SFMC`.
options.urlShortenerOptions.shortenerType	string		The type of URL shortener. The values is `SFMC`.
options.SmsMessageRegulatoryAuthorityTemplateId	string		The ID of the DLT template used in the SMS. This attribute is available only for customers in India.<br><br>Important: If you use link shortening, set this field. Otherwise, the shortened URL won't include the required regulatory header, and the SMS won't deliver. Ensure that SMS_DLT_TEMPLATES business rule is enabled.

Responses

Status	Name	Type	Description
200			Send definition is updated. Review example response.
	requestId	string	The unique identifier of this request.
	name	string	Name of the definition.
	definitionKey	string	Unique, user-generated key to access the definition object.
	definitionId	string	A unique object ID.
	description	string	User-provided description of the send definition.
	status	string	Operational state of the definition: active, inactive, or deleted. A message sent to an active definition is processed and delivered. A message sent to an inactive definition isn’t processed or delivered. Instead, the message is queued for later processing for up to three days.
	createdDate	string	Date the definition was created.
	modifiedDate	string	Date and time the definition was most recently changed.
	content.message	string	The message content that you want sent with each message. Use substitution strings and AMPscript to personalize the message.
	subscriptions.shortCode	string	The short or long code for the mobile transmissions for each message on this definition.
	subscriptions.countryCode	string	The country code associated with the shortCode for the mobile transmissions for each message on this definition. Don't use for long codes, unless your account configuration requires it.
	subscriptions.keyword	string	The keyword used to track messages
	subscriptions.autoAddSubscriber	boolean	Allows you to add a recipient as subscriber against the shortCode using contactKey. When false, the message is rejected if contactKey doesn’t exist as a subscriber. Default is true.
	subscriptions.updateSubscriber	boolean	Updates the recipient subscriber data including mobile number. Default is true.
	options.urlShortenerOptions.IsLinkShorteningEnabled	boolean	Indicates if URL shortening is enabled for URLs in the message body. The values are `true` and `false`. This attribute is available only for orgs using Hyperforce.
	options.urlShortenerOptions.isSubscriberTrackingEnabled	boolean	Indicates if subscriber level tracking is enabled for URLs in the message body. The values are `true` and `false`. The value is `true` if the value of shortenerType is `SFMC`. This attribute is available only for orgs using Hyperforce.
	options.urlShortenerOptions.shortenerType	string	The type of URL shortener. The values is `SFMC`. This attribute is available only for orgs using Hyperforce.
	options.SmsMessageRegulatoryAuthorityTemplateId	string	The ID of the DLT template used in the SMS.

Usage

Example Request

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
PATCH /messaging/v1/sms/definitions/2FA_order_accounts
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "description": "description updated",
  "content": {
        "message": "In future"
    },
    "subscriptions": {
        "shortCode": "519000242",
        "countryCode": "US",
        "keyword": "API"
    },
    "options": {
        "urlShortenerOptions": {
            "isLinkShorteningEnabled": true,
            "isSubscriberTrackingEnabled": false,
            "shortenerType": "SFMC"
        },
        "smsMessageRegulatoryAuthorityTemplateId": "1107170833298425627"
    }
}

Example Response

HTTP/1.1 200 OK
{
  "requestId": "582bec09-6d04-4222-bbba-cea616495596",
  "name": "account-reset",
  "definitionKey": "account-reset",
  "description": "description updated",
  "status": "Active",
  "createdDate": "2024-07-10T04:20:00",
  "modifiedDate": "2024-07-10T04:30:00",
  "content": {
    "message": "In future"
    },
  "subscriptions": {
    "shortCode": "519000242",
    "countryCode": "US",
    "autoAddSubscriber": true,
    "updateSubscriber": true,
    "keyword": "API"
   },
  "options": {
    "urlShortenerOptions": {
        "isLinkShorteningEnabled": true,
        "isSubscriberTrackingEnabled": false,
        "shortenerType": "SFMC"
   },
   "smsMessageRegulatoryAuthorityTemplateId": "1107170833298425627"
 }
}

HTTP Responses

Response	Reason
200 OK	Send definition is updated. Review example response.
400 Bad Request	Invalid request
403 Forbidden	Failed to pass authorization.
500 Server Error	Internal error