POST /messaging/v1/email/definitions

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.

You can’t 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 web interface and using an API. It doesn’t apply to the Journey Builder email activity triggered send definition.

Name	Type		Description
definitionKey	string	Required	Unique, user-generated key to access the definition object.
name	string	Required	Name of the definition. Must be unique.
content.customerKey	string	Required	Unique identifier of the content asset.
status	string		Operational 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.
description	string		User-provided description of the send definition.
classification	string		The external key of a sending classification defined in Email Studio Administration. Only transactional classifications are permitted. Default is default transactional.
subscriptions.list	string	Required	The external key of the list or all subscribers. Contains the subscriber keys and profile attributes.
subscriptions.dataExtension	string		The 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.autoAddSubscriber	boolean		Adds the recipient’s email address and contact key as a subscriber key to subscriptions.list. Default is true.
subscriptions.updateSubscriber	boolean		Updates the recipient’s contact key as a subscriber key with the provided email address and profile attributes to subscriptions.list. Default is true.
options.trackLinks	boolean		Wraps links for tracking and reporting. Default is true.
options.cc	array		Include CC email addresses with every send. To CC dynamically at send time, create a profile attribute and use the %%attribute%% syntax.
options.bcc	array		Include BCC email addresses with every send. To BCC dynamically at send time, create a profile attribute and use the %%attribute%% syntax.
options.createJourney	boolean		A 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.

Status	Name	Type	Description
201			Send definition is created. Review example response.
	requestId	string	The unique identifier of this request.
	name	string	Name of the definition.
	definitionKey	string	Unique, user-generated key to access the definition object.
	definitionId	string	A unique object ID.
	description	string	User-provided description of the send definition.
	classification	string	The external key of a sending classification defined in Email Studio Administration. Only transactional classifications are permitted. Default is default transactional.
	status	string	Operational 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.
	createdDate	string	Date the definition was created.
	modifiedDate	string	Date and time the definition was most recently changed.
	content.customerKey	string	Unique identifier of the content asset.
	subscriptions.dataExtension	string	The external key of the triggered send data extension. Each request inserts as a new row in the data extension.
	subscriptions.list	string	The external key of the list or all subscribers. Contains the subscriber keys and profile attributes.
	subscriptions.autoAddSubscriber	boolean	Adds the recipient’s email address and contact key as a subscriber key to subscriptions.list. Default is true.
	subscriptions.updateSubscriber	boolean	For email only: Updates the recipient’s contact key as a subscriber key with the provided email address and profile attributes to subscriptions.list. Default is true.
	options.trackLinks	boolean	Wraps links for tracking and reporting. Default is true.

If there are several email addresses in CC or BCC fields, they should be separated by a semicolon.

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