--- schema_version: "1" id: fd45f5acb3f50d1273ecec93ff264d8bc5c3607d4500672e7bfe63957b3a197e title: Email - Manage Send Definitions (REST API) collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/mc-core/references/generated-api-specs/mc-next-email-send-definitions.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-next-email-send-definitions source_site: developer.salesforce.com content_type: documentation content_hash: eed494fd3fcab27b090536936771f8e4a71be99558e5cecf723084220eae1506 products: - Marketing Cloud Next - Marketing Cloud --- Email - Manage Send Definitions (REST API) # Email - Manage Send Definitions (REST API) Manage send definitions for sending transactional emails. A send definition is a configuration record that links email content to sending parameters. Salesforce REST API manages email send definitions. All operations require authentication with a Bearer token. This table lists the use cases that the API supports. | Supported Use Case | HTTP Verb | URI | | --- | --- | --- | | Create a send definition | [POST](/docs/marketing/marketing-cloud-growth/references/mc-next-email-send-definitions?meta=createSendDefinition) | /sobjects/ListEmail | | Retrieve a send definition | [GET](/docs/marketing/marketing-cloud-growth/references/mc-next-email-send-definitions?meta=getSendDefinition) | /sobjects/ListEmail/{id} | | Update a send definition | [PATCH](/docs/marketing/marketing-cloud-growth/references/mc-next-email-send-definitions?meta=updateSendDefinition) | /sobjects/ListEmail/{id} | | Query send definitions | [GET](/docs/marketing/marketing-cloud-growth/references/mc-next-email-send-definitions?meta=querySendDefinitions) | /query | **Version:** 1.0.0 Contact: Salesforce Marketing Cloud, https://developer.salesforce.com ## Servers * `https://{subdomain}.my.salesforce.com/services/data/{versionNumber}` Salesforce REST API * `subdomain (default n/a) Your Salesforce tenant-specific subdomain.` * ``versionNumber (default n/a) The Salesforce API version number, such as `v68.0`.`` ## Operations ### POST Create a send definition `POST /sobjects/ListEmail` Operation ID: `createSendDefinition`. Tags: Send Definitions. Creates a ListEmail record that contains a send definition. Use the resulting send definition ID in requests to Direct Email Send API. #### Request body (required) Media type: `application/json`. Schema: `SendDefinitionCreate`. _Example_ ``` { "Name": "welcome-email@1.0.0", "FromName": "Northern Trail Outfitters", "FromAddress": "noreply@example.com", "ReplyToAddress": "support@example.com", "ManagedContentId": "20YSB000004Fzs52AC", "MessagePurpose": "Transactional", "IsOpenTrackingEnabled": true, "IsClickTrackingEnabled": true, "Status": "Draft" } ``` #### Responses * **201** Send definition created successfully. Media type: `application/json`. Schema: `object`. * `id` (_string_) The new send definition ID. * `success` (_boolean_) Indicates whether the operation succeeded. * `errors` (_array of object_) Array of errors if the operation failed. _Example_ ``` { "id": "0XBSG000000NY5p4AG", "success": true, "errors": [] } ``` * **400** Bad Request - Invalid field values or missing required fields Media type: `application/json`. Schema: `SalesforceError`. _Example: duplicateValue_ Duplicate Name ``` [ { "message": "duplicate value found: Name duplicates value on record", "errorCode": "DUPLICATE_VALUE", "fields": [ "Name" ] } ] ``` _Example: fieldIntegrity_ Unverified From Address ``` [ { "message": "The FromAddress is not verified", "errorCode": "FIELD_INTEGRITY_EXCEPTION", "fields": [ "FromAddress" ] } ] ``` * **401** Unauthorized - Invalid or expired token Media type: `application/json`. Schema: `SalesforceError`. * **403** Forbidden - Insufficient permissions or feature not enabled Media type: `application/json`. Schema: `SalesforceError`. _Example: insufficientAccess_ Insufficient Access ``` [ { "message": "insufficient access rights on object id", "errorCode": "INSUFFICIENT_ACCESS" } ] ``` _Example: featureNotEnabled_ Feature Not Enabled ``` [ { "message": "Access denied: feature not enabled for tenant", "errorCode": "FEATURE_NOT_ENABLED" } ] ``` ### GET Retrieve a send definition `GET /sobjects/ListEmail/{id}` Operation ID: `getSendDefinition`. Tags: Send Definitions. Retrieves a send definition by its ID. #### Parameters * `id` (path, string, required) The send definition ID. Pattern: ^\[a-zA-Z0-9\]+. _Example_ ``` 0XBSG000000NY5p4AG ``` #### Responses * **200** Send definition retrieved successfully Media type: `application/json`. Schema: `SendDefinition`. _Example_ ``` { "Id": "0XBSG000000NY5p4AG", "Name": "welcome-email@1.0.0", "FromName": "Northern Trail Outfitters", "FromAddress": "noreply@example.com", "ReplyToAddress": "support@example.com", "ManagedContentId": "20YSB000004Fzs52AC", "MessagePurpose": "Transactional", "IsOpenTrackingEnabled": true, "IsClickTrackingEnabled": true, "Status": "Draft", "Description": "Welcome email template" } ``` * **401** Unauthorized - Invalid or expired token Media type: `application/json`. Schema: `SalesforceError`. * **404** Not Found - The send definition specified in the request doesn’t exist. Media type: `application/json`. Schema: `SalesforceError`. ### PATCH Update a send definition `PATCH /sobjects/ListEmail/{id}` Operation ID: `updateSendDefinition`. Tags: Send Definitions. Updates a send definition. Include only the fields that you want to change. #### Parameters * `id` (path, string, required) The send definition ID. Pattern: ^\[a-zA-Z0-9\]+. _Example_ ``` 0XBSG000000NY5p4AG ``` #### Request body (required) Media type: `application/json`. Schema: `SendDefinitionUpdate`. _Example_ ``` { "FromName": "Updated Team Name", "IsOpenTrackingEnabled": false } ``` #### Responses * **204** The send definition was updated successfully. * **400** Bad Request - The value of a field in the request was invalid. Media type: `application/json`. Schema: `SalesforceError`. * **401** Unauthorized - The authorization token is invalid or expired. Media type: `application/json`. Schema: `SalesforceError`. * **403** Forbidden - The permissions associated with the token are insufficient to perform the action. Media type: `application/json`. Schema: `SalesforceError`. * **404** Not Found - The email send definition doesn’t exist. Media type: `application/json`. Schema: `SalesforceError`. ### GET Query send definitions `GET /query` Operation ID: `querySendDefinitions`. Tags: Send Definitions. Query send definitions with a Salesforce Object Query Language (SOQL) query. #### Parameters * `q` (query, string, required) A SOQL query string. _Example: listRecent_ List recent send definitions. ``` SELECT Id, Name, FromName, Status FROM ListEmail WHERE Status != 'Deleted' ORDER BY CreatedDate DESC LIMIT 10 ``` _Example: findByName_ Find a send definition by name. ``` SELECT Id, Name, ManagedContentId, Status FROM ListEmail WHERE Name = 'welcome-email@1.0.0' ``` _Example: filterByFromAddress_ Filter send definitions by From address. ``` SELECT Id, Name, FromAddress, MessagePurpose FROM ListEmail WHERE FromAddress = 'noreply@example.com' AND Status = 'Draft' ``` _Example: findByContent_ Find send definitions by managed content ID. ``` SELECT Id, Name, FromName, Status FROM ListEmail WHERE ManagedContentId = '20YSB000004Fzs52AC' ``` #### Responses * **200** The query executed successfully. Media type: `application/json`. Schema: `object`. * `totalSize` (_integer_) The number of records that the query returned. * `done` (_boolean_) Indicates whether all records were returned in the response. * `records` (_array of SendDefinition_) An array that contains send definition records. _Example_ ``` { "totalSize": 2, "done": true, "records": [ { "Id": "0XBSG000000NY5p4AG", "Name": "welcome-email@1.0.0", "FromName": "Northern Trail Outfitters", "Status": "Draft" }, { "Id": "0XBSG000000NY5p5AG", "Name": "event-reminder@1.0.0", "FromName": "NTO Events", "Status": "Active" } ] } ``` * **400** Bad Request - The SOQL query in the request was invalid. Media type: `application/json`. Schema: `SalesforceError`. * **401** Unauthorized - The token used in the request was invalid or expired. Media type: `application/json`. Schema: `SalesforceError`. ## Schemas ### SendDefinitionCreate An object that contains the fields used to create a send definition. * `Name` (_string_, required) A unique identifier for the definition. Use the format `package-name@version`. Example: `welcome-email@1.0.0`. * `FromName` (_string_, required) The sender display name. Example: `Northern Trail Outfitters Team`. * `FromAddress` (_string (email)_, required) The verified sender email address. The address you specify must be verified in your org. Example: `noreply@example.com`. * `ReplyToAddress` (_string (email)_) The reply-to email address. Example: `support@example.com`. * `ManagedContentId` (_string_, required) The CMS content record ID. The content you specify must be published. Pattern: ^\[a-zA-Z0-9\]+. Example: `20YSB000004Fzs52AC`. * `MessagePurpose` (_string_, required) The email classification: * `Transactional`: Operational, service-related email, such as order confirmations, password resets, account notifications, or shipping updates. * `Commercial`: Marketing and promotional messages, such as newsletters, product promotions, event invitations, or surveys. Allowed values: `Transactional`, `Commercial`. * `IsOpenTrackingEnabled` (_boolean_, required) Indicates whether to track email opens using a tracking pixel. * `IsClickTrackingEnabled` (_boolean_, required) Indicates whether to track link clicks by rewriting URLs. * `Status` (_string_) The status of the send definition. Allowed values: `Draft`, `Active`, `Deleted`. Default: `Draft`. * `Description` (_string_) An internal description of the definition. * `CampaignId` (_string_) The associated Salesforce Campaign reference. ### SalesforceError Salesforce error response. Array of `object`. * `message` (_string_) A human-readable error message. * `errorCode` (_string_) A machine-readable error code. * `fields` (_array of string_) An array that lists the fields that caused the error. ### SendDefinition A complete send definition record. * `Id` (_string_) The send definition record ID. Pattern: ^\[a-zA-Z0-9\]+. Example: `0XBSG000000NY5p4AG`. * `Name` (_string_) A unique identifier for the definition. Example: `welcome-email@1.0.0`. * `FromName` (_string_) The sender display name. Example: `Northern Trail Outfitters Team`. * `FromAddress` (_string (email)_) The verified sender email address. Example: `noreply@example.com`. * `ReplyToAddress` (_string (email)_) The reply-to email address. Example: `support@example.com`. * `ManagedContentId` (_string_) The CMS content record ID. Pattern: ^\[a-zA-Z0-9\]+. Example: `20YSB000004Fzs52AC`. * `MessagePurpose` (_string_) Allowed values: `Transactional`, `Commercial`. * `IsOpenTrackingEnabled` (_boolean_) Indicates whether email opens are tracked. * `IsClickTrackingEnabled` (_boolean_) Indicates whether link clicks are tracked. * `Status` (_string_) Allowed values: `Draft`, `Active`, `Deleted`. * `Description` (_string_) An internal description of the definition. * `CampaignId` (_string_) The associated Salesforce Campaign reference. * `CreatedDate` (_string (date-time)_, read-only) When the record was created. * `LastModifiedDate` (_string (date-time)_, read-only) When the record was last modified. ### SendDefinitionUpdate Fields for updating a send definition. Include only the fields that you want to change. * `Name` (_string_) A unique identifier for the definition. * `FromName` (_string_) The sender display name. * `FromAddress` (_string (email)_) The verified sender email address. * `ReplyToAddress` (_string (email)_) The reply-to email address. * `ManagedContentId` (_string_) The CMS content record ID. * `MessagePurpose` (_string_) Allowed values: `Transactional`, `Commercial`. * `IsOpenTrackingEnabled` (_boolean_) Indicates whether to track email opens. * `IsClickTrackingEnabled` (_boolean_) Indicates whether to track link clicks. * `Status` (_string_) Allowed values: `Draft`, `Active`, `Deleted`. * `Description` (_string_) * `CampaignId` (_string_)