Manage a transactional campaign

Post https://{hostname}/v3/campaigns/transactional/send.{format}?apikey=

Sends a transactional campaign to your recipients. You can add content by either creating a campaign inside Sitecore Send and designing the template in the editor (provide the template ID), by providing the HTML body in the API, or by providing a web location.

If a TemplateId is not provided and the TemplateName exists within the platform, the existing campaign will be sent. If the TemplateId is not provided and the TemplateName does not exist within the platform, a new transactional campaign will be created. The payload size provided per API call must be less than 20MB.

Request

Parameter	In	Type	Required	Description
`Accept`	header	string	true	Determines the expected format and data type to retrieve the response data. Value: `application/json`
`apikey`	query	string	true	The API key of your account.
`From`	body	object	false	An array containing the parameters of the sender: Email - the email address of a verified sender. sendersName - the name of the sender name displayed in the recipient's inbox.
`ReplyTo`	body	object	false	An array containing the parameters of the sender the user can reply to: Email - the email address of one of a verified sender. sendersName - the name of the Reply to email displayed to the user when the user clicks Reply.
`Subject`	body	string	false	The subject line of the email message displayed to the recipient. It may contain parameters for personalization. When no value is provided, use the subject of the template.
`TemplateId`	body	GUID	false	Statistics will be registered to the campaign with this ID. If you have created a template id, you can find it in the user interface. If the array `content` is empty or doesn’t exist, then the content for the email is taken from the template id provided.
`TemplateName`	body	string	false	The name of the transactional campaign that this message will be sent for. Transactional campaign names are unique. If the array `content` is empty or doesn’t exist, then the content for the email is taken from the template name provided.
`Content`	body	array	false	Content types: Type - the type of content to send. Value - the format specified by `content.type`. It may contain parameters to be substituted for each recipient, according to the parameters given in the personalization property. WebLocation - the URL that holds the content to use for this this message. To reuse it for the next requests and avoid re-downloading, cache it to S3 for 24 hours. Only one `content` should exist in the payload for the call to be valid. If there is a content and template ID or name, then the content overrules and the template ID is kept to show the location of the statistics.
`Personalizations`	body	array	true	A list of recipients of the transactional message. It may contain personalization parameters. To - an array containing the parameters of the receiver Email - the recipient email address (text/plain). Name - the recipient name (text/plain). Substitutions - the values to substitute in the message content/subject for the current recipient, in the form of key/value pairs. There are some restricted keywords implemented, see note below.
`MailSettings`	body	array	true	When set to `true` or omitted, the message will be delivered to the recipient, even if they have unsubscribed from the transactional email list. Default: `true` BypassUnsubscribeManagement Enable - `true` (default) / `false`
`attachments`	body	object	false	An array containing the parameters of the attachments: - Content - A base64 string that represents the file bytes of the attachment (Required). Type - The MIME type of the attached content (e.g. application/pdf, image/PNG) (Required). FileName - The file name of the attachment that the recipient will see (Required). Disposition - Allowed values are: “inline”, “attachment” (Required). ContentId - A user-defined string that maps an embedded image to an attachment. (Required only for inline disposition).

Note

Restricted keywords for substitutions: datetime, ab, appDomain, appDomainProtocol, trackingDomain, doubleOptInDomain, utilitiesDomain, updatePreferences, emailSentTo, forwardToFriendLink, updateProfileLink, verificationLink, unsubscribeLink.

RequestResponse

POST /v3/campaigns/transactional/send.json?apikey=

Request body: {

{ 
    "From": {
        "Email": "[email protected]",
        "Name": "Example Order Confirmation"
    }, 
    "ReplyTo": { 
        "Email": "[email protected]", 
        "Name": "Example Customer Service Team" 
    }, 
    "Subject": "Your Example Order Confirmation", 
    "TemplateId": "d59b39d5-da76-4797-8f24-c1265bb903b8", 
    "TemplateName": "My Sending Template", 
    "Content": [ 
        { 
            "Type": "text/html", 
            "Value": "<p>Hello world</p>", 
            "WebLocation": "https://mycompany.com/template.html" 
        } 
    ], 
    "Personalizations": [ 
        { 
            "To": [ 
                { 
                    "Email": "[email protected]", 
                    "Name": "John Doe" 
                } 
            ], 
            "Substitutions": { 
                    "key1": "value1", 
                    "key2": "value2" 
                } 
        }, 
        { 
            "To": [ 
                { 
                    "Email": "[email protected]", 
                    "Name": "Julia Doe" 
                } 
            ], 
            "Substitutions": { 
                    "key1": "value1", 
                    "key2": "value2" 
                } 
        } 
    ], 
    "MailSettings": { 
        "BypassUnsubscribeManagement": { 
            "Enable": true 
        } 
    },
    "ReplyTo": {
        "Email": "[email protected]",
        "Name": "Example Customer Service Team"
      "Type": "application/pdf",
      "FileName": "attachementexample.pdf",
      "disposition": "attachment",
      "ContentId": "attachment-a"
    },
    "Subject": "Your Example Order Confirmation",
    "TemplateId": "d59b39d5-da76-4797-8f24-c1265bb903b8",
    "TemplateName": "My Sending Template",
    "Content": [
        {
            "Type": "text/html",
            "Value": "<p>Hello world</p>",
            "WebLocation": "https://mycompany.com/template.html"
        }
    ],
    "Personalizations": [
        {
            "To": [
                {
                    "Email": "[email protected]",
                    "Name": "John Doe"
                }
            ],
            "Substitutions": {
                "key1": "value1",
                "key2": "value2"
            },
            "details": {
                "firstchild": "firstchildvalue",
                "firstchild2": "firstchild2value",
                "firstchild3": {
                    "secondchild": {
                        "nestierchild": "nestierchildvalue"
                    }
                },
                "firstchild4": {
                    "secondchild": "nestierchild4value"
                }
            }
        },
        {
            "To": [
                {
                    "Email": "[email protected]",
                    "Name": "Julia Doe"
                }
            ],
            "Substitutions": {
                "key1": "value1",
                "key2": "value2"
            }
        }
    ],
    "MailSettings": {
        "BypassUnsubscribeManagement": {
            "Enable": true
        }
    },
    "attachments": [
        {
            "content": "iVBORw0KGgoAAAANSUhEUgAABYMAAAOgCAYAAABvGmkhAAAABGdBTUEAAwAAAAA0AeMwQAAAAAAfcAYDAAAAADQB4zBAAAAAAB9wBgMAAAAANAHjMEAAAAAAH3AGAwAAAAA0AeMwQAAAAAAPe+T+J/nnNIPnRqhbwAAAABJRU5ErkJggg==",
            "Type": "application/pdf",
            "FileName": "attachementexample.pdf",
            "disposition": "attachment",
            "ContentId": "attachment-a"
        },
        {
            "content": "iVBORw0KGgoAAAAAfcAYDAAAAADQB4zBAAAAAAB9wBgMAAAAANAHjMEAAAAAAH3AGAwAAAAA0AeMwQAAAAAAfcAYDAAAAADQB4zBAAAAAAB9wBgMAAAAANAHjMEAAAAAAH3AGAwAAAAA0AeMwQAAAAAAPe+T+J/nnNIPnRqhbwAAAABJRU5ErkJggg==",
            "type": "image/PNG",
            "filename": "imageexample.png",
            "disposition": "inline",
            "contentId": "image-a"
        }
    ]
  ]
}

RequestResponse

curl --include \
     --request POST \
https: //{hostname}/v3/campaigns/transactional/send.json?apikey=
{
    "From": {
        "Email": "[email protected]",
        "Name": "Example Order Confirmation"
    }, 
    "ReplyTo": { 
        "Email": "[email protected]", 
        "Name": "Example Customer Service Team" 
    }, 
    "Subject": "Your Example Order Confirmation", 
    "TemplateId": "d59b39d5-da76-4797-8f24-c1265bb903b8", 
    "TemplateName": "My Sending Template", 
    "Content": [ 
        { 
            "Type": "text/html", 
            "Value": "<p>Hello world</p>", 
            "WebLocation": "https://mycompany.com/template.html" 
        } 
    ], 
    "Personalizations": [ 
        { 
            "To": [ 
                { 
                    "Email": "[email protected]", 
                    "Name": "John Doe" 
                } 
            ], 
            "Substitutions": { 
                    "key1": "value1", 
                    "key2": "value2" 
                } 
        }, 
        { 
            "To": [ 
                { 
                    "Email": "[email protected]", 
                    "Name": "Julia Doe" 
                } 
            ], 
            "Substitutions": { 
                    "key1": "value1", 
                    "key2": "value2" 
                } 
        } 
    ], 
    "MailSettings": { 
        "BypassUnsubscribeManagement": { 
            "Enable": true 
        } 
    },
    "ReplyTo": {
        "Email": "[email protected]",
        "Name": "Example Customer Service Team"
      "Type": "application/pdf",
      "FileName": "attachementexample.pdf",
      "disposition": "attachment",
      "ContentId": "attachment-a"
    },
    "Subject": "Your Example Order Confirmation",
    "TemplateId": "d59b39d5-da76-4797-8f24-c1265bb903b8",
    "TemplateName": "My Sending Template",
    "Content": [
        {
            "Type": "text/html",
            "Value": "<p>Hello world</p>",
            "WebLocation": "https://mycompany.com/template.html"
        }
    ],
    "Personalizations": [
        {
            "To": [
                {
                    "Email": "[email protected]",
                    "Name": "John Doe"
                }
            ],
            "Substitutions": {
                "key1": "value1",
                "key2": "value2"
            },
            "details": {
                "firstchild": "firstchildvalue",
                "firstchild2": "firstchild2value",
                "firstchild3": {
                    "secondchild": {
                        "nestierchild": "nestierchildvalue"
                    }
                },
                "firstchild4": {
                    "secondchild": "nestierchild4value"
                }
            }
        },
        {
            "To": [
                {
                    "Email": "[email protected]",
                    "Name": "Julia Doe"
                }
            ],
            "Substitutions": {
                "key1": "value1",
                "key2": "value2"
            }
        }
    ],
    "MailSettings": {
        "BypassUnsubscribeManagement": {
            "Enable": true
        }
    },
    "attachments": [
        {
            "content": "iVBORw0KGgoAAAANSUhEUgAABYMAAAOgCAYAAABvGmkhAAAABGdBTUEAAwAAAAA0AeMwQAAAAAAfcAYDAAAAADQB4zBAAAAAAB9wBgMAAAAANAHjMEAAAAAAH3AGAwAAAAA0AeMwQAAAAAAPe+T+J/nnNIPnRqhbwAAAABJRU5ErkJggg==",
            "Type": "application/pdf",
            "FileName": "attachementexample.pdf",
            "disposition": "attachment",
            "ContentId": "attachment-a"
        },
        {
            "content": "iVBORw0KGgoAAAAAfcAYDAAAAADQB4zBAAAAAAB9wBgMAAAAANAHjMEAAAAAAH3AGAwAAAAA0AeMwQAAAAAAfcAYDAAAAADQB4zBAAAAAAB9wBgMAAAAANAHjMEAAAAAAH3AGAwAAAAA0AeMwQAAAAAAPe+T+J/nnNIPnRqhbwAAAABJRU5ErkJggg==",
            "type": "image/PNG",
            "filename": "imageexample.png",
            "disposition": "inline",
            "contentId": "image-a"
        }
    ]
  ]
}'

Response

Status	Description	Headers	Schema
`200 OK`	The request is successful.	`Content-Type:application/json` `Accept:application/json`	N/A

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

RequestResponse

{
  "TotalAccepted": 1,
  "TotalExcluded": 1,
  "ExcludedRecipients": [
    {
      "Email": "[email protected]",
      "Reason": "The recipient was found with status bounced"
    }
  ]
}

Do you have some feedback for us?

If you have suggestions for improving this article,