POST /messaging/v1/sms/definitions

Creates a send definition.

NameTypeDescription
definitionKeystringRequiredUnique, user-generated key to access the definition object.
namestringRequiredName of the definition. Must be unique.
content.messagestringRequiredThe message content that you want sent with each message. Use substitution strings and AMPscript to personalize the message.
statusstringOperational 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.
descriptionstringUser-provided description of the send definition.
subscriptions.shortCodestringRequiredThe short or long code for the mobile transmissions for each message on this definition.
subscriptions.countryCodestringThe 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.keywordstringRequiredThe keyword used to track messages
subscriptions.autoAddSubscriberbooleanAllows 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.
StatusNameTypeDescription
201  Send definition is created. Review example response.
 requestIdstringThe unique identifier of this request.
 namestringName of the definition.
 definitionKeystringUnique, user-generated key to access the definition object.
 definitionIdstringA unique object identifier.
 descriptionstringUser-provided description of the send definition.
 statusstringOperational 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.
 createdDatestringDate the definition was created.
 modifiedDatestringDate and time the definition was most recently changed.
 content.messagestringThe message content that you want sent with each message. Use substitution strings and AMPscript to personalize the message.
 subscriptions.shortCodestringThe short or long code for the mobile transmissions for each message on this definition.
 subscriptions.countryCodestringThe 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.keywordstringThe keyword used to track messages
 subscriptions.autoAddSubscriberbooleanAllows 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.updateSubscriberbooleanUpdates the recipient subscriber data including mobile number. Default is true.

If autoAddSubscriber is passed as true, then updateSubscriber must be set to false.

Failing to do so results in the return of an error "{ "message": "MCMS_UTM_Validation_InvalidValue: autoAddSubscriber needs to be enabled if updateSubscribers is true.", "errorcode": 10005, "documentation": "" }".

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

The response includes information about the send definition.

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.

ResponseReason
201 CreatedSend definition is created. Review example response.
409 ConflictSend definition exists on the server.
400 Bad RequestInvalid request.
403 ForbiddenFailed to pass authorization.
500 Server ErrorInternal error.