POST /messaging/v1/email/definitions

Overview

Creates a long-living send definition object that references the email template, subscriber list, sending options, journey, and metadata. A send definition is referenced in the transactional messaging API when triggering a send to recipients. We recommend that you create one definition for each type of email or use-case. In other words, create a definition for a group of email requests, because there is a limit on the number of definitions you can create.

The transactional send definition will remain synchronized to the transactional send journey (when journey.interactionKey is provided) whether you manage the send definition through this API or the Journey Builder canvas.

NOTE: You cannot create and manage transactional send journeys using the Journey Builder API (interactions/v1/interaction/{journeyId}).

You can create only up to 500 total email transactional send definitions plus email triggered send definitions in a seven-day period for one business unit. So don't create a definition for each send request that you trigger. This limit applies to send definitions created in the Marketing Cloud application and via API. It doesn’t apply to the Journey Builder email activity triggered send definition.

JSON Parameters

NameTypeDescription
definitionKeystringRequiredUnique, user-generated key to access the definition object.
namestringRequiredName of the definition. Must be unique.
content.customerKeystringRequiredUnique identifier of the content asset.
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.
classificationstringMarketing Cloud external key of a sending classification defined in Email Studio Administration. Only transactional classifications are permitted. Default is default transactional.
subscriptions.liststringRequiredMarketing Cloud external key of the list or all subscribers. Contains the subscriber keys and profile attributes.
subscriptions.dataExtensionstringMarketing Cloud external key of the triggered send data extension. Each request inserts as a new row in the data extension. To deduplicate at send time, use messageKey. Don’t use a primary key on the triggered send data extension.
subscriptions.autoAddSubscriberbooleanAdds the recipient’s email address and contact key as a subscriber key to subscriptions.list. Default is true.
subscriptions.updateSubscriberbooleanUpdates the recipient’s contact key as a subscriber key with the provided email address and profile attributes to subscriptions.list. Default is true.
options.trackLinksbooleanWraps links for tracking and reporting. Default is true.
options.ccarrayInclude CC email addresses with every send. To CC dynamically at send time, create a profile attribute and use the %%attribute%% syntax.
options.bccarrayInclude BCC email addresses with every send. To BCC dynamically at send time, create a profile attribute and use the %%attribute%% syntax.
options.createJourneybooleanA value of true updates the send definition to make it available in Journey Builder as a Transactional Send Journey. After the definition is tied to a Transactional Send Journey, the definition remains part of Journey Builder. You can’t unlink a journey from a definition without recreating the transactional send definition.

Usage

Example Request

Example Response

HTTP Responses

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