POST /sms/v1/messageList/{id}/send

Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

Note

Initiates a message to one or more contact lists.

URL Parameters

Name	Type	Description
`messageId`	string	The encodedID can be found when creating a “API Entry Event” type Outbound message in the UI. If you have already passed that point you can find the ID by looking at the API resource behind the scenes when you open that message in the UI.

JSON Parameters

Name	Type	Description
`TargetListIds`	array	A list of one or more List ID strings. The contacts in these Lists will be included in the send and will overwrite the Message’s default inclusion lists.
`OverrideTemplateTargetLists`	string	A flag that indicates that TargetListIds are provided for overriding the default Target List Ids for the message.
`ExclusionListIds`	array	A list of one or more List ID strings. The contacts in these Lists will be excluded in the send and will overwrite the Message’s default exclusion lists.
`IgnoreExclusionLists`	boolean	A flag indicating that exclusion lists, including the default message exclusion lists, aren’t used in the send.
`OverrideMessageText`	string	A flag indicating that the text provided should override the text stored with the Message
`MessageText`	string	Required when OverrideMessageText is true
`blackoutWindow`	object	Details about the window of time where messages shouldn’t be sent. Messages initiated inside of this window will be queued and delivered once the window is open.
`blackoutWindow.UtcOffset`	string	The UTC offset of the blockoutWindow start and end times. UtcOffset is required in every REST call in order for the blockoutWindow to be honored.
`blackoutWindow.WindowStart`	string	The start time of the blockoutWindow, in the UTC offset specified. To see if the SendTime is within the blockoutWindow, convert the WindowStart and WindowEnd times to UTC and compare them to the SendTime
`blackoutWindow.WindowEnd`	string	The end time of the blockoutWindow, in the UTC offset specified. To see if the SendTime is within the blockoutWindow, convert the WindowStart and WindowEnd times to UTC and compare them to the SendTime
`sendTime`	date	Date and Time in UTC that the message will go out. Example format: `2012-10-17 17:01`. The blockoutWindow will still be respected if used with this option. If the SendTime is set to a date and time in the past, the message will send immediately.
`allowDuplication`	boolean	The same mobile number may receive multiple texts if this value is true.
`ContentURL`	string	The URL of the media content sent via an MMS message.

Usage

Example Request

1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /sms/v1/messageList/MzA6Nzg6MA/send
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7    "TargetListIds": [
8        "bzZ0cENGam1FZUtNX0poTDRYZzhlQTo2Mzow"
9    ],
10    "OverrideTemplateTargetLists": "true",
11    "OverrideTemplateExclusionLists": "false",
12    "IgnoreExclusionLists": "true",
13    "OverrideMessageText": "false",
14    "ContentURL" : "http://image.exct.net/lib/fe6d15707662057c7411/m/1/dj_CC_AUS.jpg"
15    "BlackoutWindow": {
16        "UtcOffset": "-0500",
17        "WindowStart": "1500",
18        "WindowEnd": "2200"
19    },
20    "AllowDuplication": "false"
21}

Example Response

If all values in the request are valid, the API returns a token that can be used to make a follow-up call to check the status of the request.

1HTTP/1.1 202 Accepted
2{
3  "tokenId": "c21NCNSDNsd222as85dj92j2sMMWM2miosdjEHH",
4}

Error Response

If the request wasn’t valid, the API returns a 400 response with details on the error. This example includes the following errors:

The keyword doesn’t exist in the account

The mobile number includes hyphens

1HTTP/1.1 202 Accepted
2{
3"tokenId": "c21NCNSDNsd222as85dj92j2sMMWM2miosdjEHH",
4}

Message	Details
Message id {0} isn’t valid.	The messageID value provided in the URL wasn’t in a valid format.
Message {0} isn’t valid for the client.	The messageID value included in the URL doesn’t match a valid value within the account.
The Message must be in `Active` status in order to send.	The message doesn’t have a status of `Active` or `Scheduled`.
The count of Target List IDs can’t be zero.	Indicates that no valid Target List IDs were specified.
Target list id [{0}] is invalid.	Indicates that the Target List ID specified is invalid.
TargetListIds isn’t applicable when OverrideTemplateTargetLists is false.	Indicates that the OverrideTemplateTargetLists flag wasn’t set to TRUE when specifying Target List IDs.
Cannot override template target lists when no target list ids are specified.	Indicates that no TargetListIDs were specified even though the OverrideTemplateTargetLists flag was set to TRUE.
The count of Exclusion List IDs can’t be zero.	Indicates that no valid Exclusion List IDs were specified.
Exclusion list id [{0}] is invalid.	Indicates that the Exclusion List ID specified is invalid.
ExclusionListIds isn’t applicable when OverrideTemplateExclusionLists is false.	Indicates that the OverrideTemplateExclusionLists flag wasn’t set to TRUE when specifying Exclusion List IDs.
Cannot override template exclusion lists when no exclusion list ids are specified.	Indicates that no ExclusionListIDs were specified even though the OverrideTemplateExclusionLists flag was set to TRUE.
Exclusion list ids can’t be specified when IgnoreExclusionLists is true.	Indicates that IgnoreExclusionLists was set to TRUE even though ExclusionLists were specified.
OverrideTemplateExclusionLists can’t be true when IgnoreExclusionLists is true.	Indicates that IgnoreExclusionLists was set to TRUE even though OverrideTemplateExclusionLists was also set to TRUE .
Message is blank and no override message was provided.	Indicates that the Message’s stored text is blank and no override was provided.
Cannot override message text with a blank message.	Indicates that the override flag is true but a blank or missing MessageText field was submitted.
MessageText isn’t applicable when OverrideMessageText is false.	Indicates that no MessageText is needed and shouldn’t be included in the request. This is present to eliminate confusion and errant sends with the static message text.
A UTC offset must be specified when using a blackout window.	Indicates that no UTC time zone offset was provided in the BlackoutWindow object.
{0} isn’t a valid UTC offset.	Indicates that the UTC offset provided isn’t in the correct format.
A window start time must be specified when using a blackout window.	Indicates that no blackout window start time was provided in the BlackoutWindow object.
{0} isn’t a valid blackout window start time.	Indicates that the blackout window start time isn’t in the correct format.
A window end time must be specified when using a blackout window.	Indicates that no blackout window end time was provided in the BlackoutWindow object.
{0} isn’t a valid blackout window end time.	Indicates that the blackout window end time isn’t in the correct format.
{0} isn’t a valid send time (`yyyy-MM-dd HH:mm`).	Indicates that the send time isn’t in the proper format.

DID THIS ARTICLE SOLVE YOUR ISSUE?
Let us know so we can improve!