POST /messaging/v1/email/messages/

Sends a message to multiple recipients using a send definition. You can provide a messageKey in the request. If you don't specify a messageKey one is automatically generated. You can send messages to up to 2,000 recipients per request. If you send attributes with the recipients, we recommend no more than 500 recipients per request.

NameTypeDescription
definitionKeystringRequired. The ID of the send definition.
recipientsarrayRequired. An object that contains parameters and metadata for the recipients, such as send tracking and personalization attributes. If this object is present in the request, the recipient array (which is used to send messages to a single recipient) can't be included in the request.
recipients.contactKeystringRequired. A unique identifier for the subscriber. You can create a contact key at send time if the contact isn’t already in Marketing Cloud Engagement.
recipients.tostringThe recipient's email address.
recipients.messageKeystringA unique identifier that you can use to track the status of the message. You can provide this key as part of the request. If you don't provide a key, the system generates one for you. The key can contain up to 100 characters. There are no character restrictions. The message key that you provide must be unique among all of the keys that have been used in your business unit over the prior 72 hours. If you use a duplicate messageKey in the same send request, the message is rejected.
recipients.attributesobjectPersonalization information for the recipient. Written as key-value pairs. The attributes match profile attributes, content attributes, or triggered send data extension attributes.
attributesobjectInformation used to personalize the message for the request. Written as key-value pairs. The attributes match profile attributes, content attributes, or triggered send data extension attributes.

The response includes a request ID for the entire request. The responses array contains a messageKey value for each message that you attempted to send. If a message was sent successfully, the object doesn’t contain any additional information.

If a message wasn’t sent, the object in the responses array still includes a messageKey, but it also includes the reason that the message failed to send. The response can include a mix of successful and unsuccessful sends. In other words, one unsuccessful send doesn’t cause the entire batch to fail.