POST /messaging/v1/sms/definitions

Creates an SMS send definition.

JSON Parameters

Name	Type	Description
`definitionKey`	String	Required. A unique key for the SMS send definition object.
`name`	String	Required. A unique name for the send definition.
`content.message`	String	Required. The message content for the send definition. You can personalize the message by including AMPscript in the message body.
`status`	String	The state of the send definition. Possible values are `active` or `inactive`. 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	A description of the send definition.
`subscriptions.shortCode`	String	Required. The short or long code to send messages from.
`subscriptions.countryCode`	String	The country code associated with the short code. Don’t specify this value for long codes unless your account configuration requires it.
`subscriptions.keyword`	String	Required. The keyword used to track messages.
`subscriptions.autoAddSubscriber`	Boolean	Indicates whether to add a recipient as a short code subscriber by contact key. If this value is `false`, the message is rejected if the subscriber’s contact key doesn’t exist. The default value is `true`.
`subscriptions.updateSubscriber`	Boolean	Indicates whether to update the subscriber data for the recipient, including their mobile number. The default value is `true`.
`options.urlShortenerOptions.IsLinkShorteningEnabled`	Boolean	Indicates whether to enable URL shortening for URLs in the message body.
`options.urlShortenerOptions.isSubscriberTrackingEnabled`	Boolean	Indicates whether to enable subscriber-level tracking for URLs in the message body. The value is `true` if the value of `shortenerType` is `SFMC`.
`options.urlShortenerOptions.shortenerType`	String	The type of URL shortener to use in the send definition. The only accepted value is `SFMC`.
`options.SmsMessageRegulatoryAuthorityTemplateId`	String	The ID of the DLT template used in the SMS. This attribute applies only to senders based 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.

note: If the value of updateSubscriber is true, then autoAddSubscriber must also be true. The API returns an error if updateSubscriber is true but autoAddSubscriber is false.

Response Parameters

Name	Type	Description
`requestId`	String	A unique identifier for the request.
`name`	String	The name of the SMS send definition.
`definitionKey`	String	The unique key of the SMS send definition.
`definitionId`	String	A unique identifier for the send definition.
`description`	String	A description of the send definition.
`status`	String	The state of the send definition. Possible values are `Active`, `Inactive`, or `Deleted`.
`createdDate`	String	The date and time when the definition was created.
`modifiedDate`	String	The date and time when the definition was last modified.
`content.message`	String	The message content for the send definition.
`subscriptions.shortCode`	String	The short or long code associated with the send definition.
`subscriptions.countryCode`	String	The country code associated with the short code for the send definition.
`subscriptions.keyword`	String	The keyword used to track messages.
`subscriptions.autoAddSubscriber`	Boolean	Indicates whether to add a recipient as a short code subscriber by contact key.
`subscriptions.updateSubscriber`	Boolean	Indicates whether the subscriber data for the recipient is updated.
`options.urlShortenerOptions.IsLinkShorteningEnabled`	Boolean	Indicates whether URL shortening is enabled for URLs in the message body.
`options.urlShortenerOptions.isSubscriberTrackingEnabled`	Boolean	Indicates whether subscriber-level tracking is enabled for URLs in the message body.
`options.urlShortenerOptions.shortenerType`	String	The type of URL shortener used in the send definition.
`options.SmsMessageRegulatoryAuthorityTemplateId`	String	The ID of the DLT template used in the SMS.

Usage

To associate a short code to a send definition, use the alphabetic countryCode and numeric shortCode attributes.

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

{
  "definitionKey": "account-reset",
  "name": "account-reset",
  "description": "Using SMS Transactional API",
  "content": {
    "message": "%%FirstName%%, your 2FA token is %%password%%"
  },
  "subscriptions": {
    "shortCode": "8201221",
    "countryCode": "US",
    "keyword": "PASSWORD"
  },
  "options": {
     "urlShortenerOptions" : {
       "isLinkShorteningEnabled": true,
       "isSubscriberTrackingEnabled":true,
       "shortenerType":"SFMC"
   },
   "smsMessageRegulatoryAuthorityTemplateId": "1107170833298425627"
}
}

A successful request produces a 201 Created response that includes information about the send definition, as shown in this example.

{
  "requestId": "582bec09-6d04-4222-bbba-cea616495596",
  "name": "account-reset",
  "definitionKey": "account-reset",
  "description": "Using new SMS Transactional API",
  "status": "Active",
  "createdDate": "2019-05-14T21:05:00",
  "modifiedDate": "2019-05-14T21:05:00",
  "content": {
    "message": "%%FirstName%%, your 2FA token is %%password%%"
  },
  "subscriptions": {
    "shortCode": "8201221",
    "countryCode": "US",
    "autoAddSubscriber": true,
    "updateSubscriber": true,
    "keyword": "PASSWORD"
  },
  "options": {
    "urlShortenerOptions": {
      "isLinkShorteningEnabled": true,
      "isSubscriberTrackingEnabled": true,
      "shortenerType": "SFMC"
    },
    "smsMessageRegulatoryAuthorityTemplateId": "1107170833298425627"
  }
}

SMS Send Definition with a Long Code

To associate a long code or international phone number to a send definition, add the numeric country code at the beginning of the phone number. Then, use this number as the shortCode attribute. Don't use the alphabetic countryCode attribute unless your account configuration requires it.

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

{
  "definitionKey": "account-reset",
  "name": "account-reset",
  "description": "Using new SMS Transactional API",
  "content": {
    "message": "%%FirstName%%, your 2FA token is %%password%%"
  },
  "subscriptions": {
    "shortCode": "971234567890",
    "keyword": "PASSWORD"
  },
  "options": {
     "urlShortenerOptions" : {
       "isLinkShorteningEnabled": true,
       "isSubscriberTrackingEnabled":true,
       "shortenerType":"SFMC"
    },
    "smsMessageRegulatoryAuthorityTemplateId": "1107170833298425627"
  }
}

A successful request produces a 201 Created response that includes information about the send definition, as shown in this example.

{
  "requestId": "582bec09-6d04-4222-bbba-cea616495596",
  "name": "account-reset",
  "definitionKey": "account-reset",
  "description": "Using new SMS Transactional API",
  "status": "Active",
  "createdDate": "2019-05-14T21:05:00",
  "modifiedDate": "2019-05-14T21:05:00",
  "content": {
    "message": "%%FirstName%%, your 2FA token is %%password%%"
  },
  "subscriptions": {
    "shortCode": "971234567890",
    "autoAddSubscriber": true,
    "updateSubscriber": true,
    "keyword": "PASSWORD"
  },
  "options": {
    "urlShortenerOptions": {
      "isLinkShorteningEnabled": true,
      "isSubscriberTrackingEnabled": true,
      "shortenerType": "SFMC"
    },
    "smsMessageRegulatoryAuthorityTemplateId": "1107170833298425627"
  }
}

HTTP Responses

Response	Reason
`201 Created`	Send definition created.
`409 Conflict`	Send definition exists on the server.
`400 Bad Request`	Invalid request.
`403 Forbidden`	Failed to pass authorization.
`500 Server Error`	Internal error.