---
title: Message senders
slug: message-senders
abstract: Message senders deliver event-driven notifications to users based on key commerce activities
content_type: concept
audience: \[developer, architect]
---
# Message Senders

Message Senders help to deliver event-driven notifications to users based on certain key commerce activities. OrderCloud defines the activities, which could be things like order submitted, order shipped, forgot password, etc. and leaves it open to you to decide the presentation and notification format such as email, text, or perhaps something else completely.

## Message Senders vs Webhooks

[Webhooks](https://doc.sitecore.com/ordercloud/en/developers/platform/webhooks.html) are another OrderCloud feature that are event-driven and could conceivably be used to drive notifications, but webhooks are much less suited than message senders for this task. For example consider trying to build a notification to all users who are able to approve a newly submitted order. To accomplish this with webhooks you would need write code to cover the following steps:

1. Build a handler to receive the submit for your approval webhook

2. Take the high level order information and query the API for the rest of the needed order data

3. Query the API for all of the possible approving users (which can be complex)

4. Look up approving users' contact information

5. Send each message


In contrast, an `OrderSubmittedForYourApproval` message sender will retrieve all of the relevant information for you and send a single web request for each approver message that should be sent. This enables you to write a single, simple handler whose sole responsibility is to format the message and send it via email, text, or whichever other format you desire.

## Message Sender Types

The message sender types below outline all of the different commerce activities that can trigger a notification via message senders. If you're not seeing an activity that you would expect, please reach out to us and we will consider adding it.

Note: A user must be active in order to receive a message. This means that user `Active=true` but also that buyer `Active=true` for the buyer organization they belong to or supplier `Active=true` for the supplier organization they belong to

| Message Type | Description |
| --- | --- |
| NewUserInvitation | Notify the buyer user when an admin user [creates them](https://api-docs.sitecore.com/ordercloud/users/users.create) or when they [self register](https://api-docs.sitecore.com/ordercloud/me/me.register) |
| ForgottenPassword | Notify the user when they initiate a [password reset](https://api-docs.sitecore.com/ordercloud/forgotten-credentials/forgottencredentials.sendverificationcode) [request](https://api-docs.sitecore.com/ordercloud/forgotten-credentials/forgottencredentials.sendverificationcode) |
| OrderSubmitted | Notify the buyer user when they [submit an order](https://api-docs.sitecore.com/ordercloud/orders/orders.submit) |
| OrderSubmittedForApproval | Notify the buyer user when their order has [been submitted](https://api-docs.sitecore.com/ordercloud/orders/orders.submit), but has been placed on hold pending approval |
| OrderApproved | Notify the buyer user when the order that was previously on hold, [has been approved](https://api-docs.sitecore.com/ordercloud/orders/orders.approve) and released for fulfillment |
| OrderDeclined | Notify the buyer user when the order that was previously on hold, [has been declined](https://api-docs.sitecore.com/ordercloud/orders/orders.decline) and will not be fulfilled |
| OrderSubmittedForYourApproval | Notify approving users that there is a new order pending their approval |
| OrderSubmittedForYourApprovalHasBeenApproved | Notify approving users that an order that was previously on hold pending their approval [has been approved](https://api-docs.sitecore.com/ordercloud/orders/orders.approve) |
| OrderSubmittedForYourApprovalHasBeenDeclined | Notify approving users that an order that was previously on hold pending their approval [has been declined](https://api-docs.sitecore.com/ordercloud/orders/orders.decline) |
| ShipmentCreated | Notify the buyer user when a shipment was made for their order. Please note triggering this requires a very specific order of operations. First, the shipment must be created with a `ShippedDate` set to `null`, then the relevant shipment items should be added to the shipment, and finally the shipment should be patched with a `ShippedDate` |
| OrderReturnSubmitted | Notify the buyer user when they [submit an order return](https://api-docs.sitecore.com/ordercloud/order-returns/orderreturns.submit) |
| OrderReturnSubmittedForApproval | Notify the buyer user when their order has [been submitted](https://api-docs.sitecore.com/ordercloud/order-returns/orderreturns.submit), but has been placed on hold pending approval |
| OrderReturnApproved | Notify the buyer user when the order that was previously on hold, [has been approved](https://api-docs.sitecore.com/ordercloud/order-returns/orderreturns.approve) and released for fulfillment |
| OrderReturnDeclined | Notify the buyer user when the order return that was previously on hold, [has been declined](https://api-docs.sitecore.com/ordercloud/order-returns/orderreturns.decline) and will not be fulfilled |
| OrderReturnSubmittedForYourApproval | Notify approving users that there is a new order return pending their approval |
| OrderReturnSubmittedForYourApprovalHasBeenApproved | Notify approving users that an order return that was previously on hold pending their approval [has been approved](https://api-docs.sitecore.com/ordercloud/order-returns/orderreturns.approve) |
| OrderReturnSubmittedForYourApprovalHasBeenDeclined | Notify approving users that an order return that was previously on hold pending their approval [has been declined](https://api-docs.sitecore.com/ordercloud/order-returns/orderreturns.decline) |
| OrderReturnCompleted | Notify buyer users that an order return they submitted [is now complete](https://api-docs.sitecore.com/ordercloud/order-returns/orderreturns.complete) |
| OneTimePassword | Deliver a [one-time password](https://ordercloud.io/knowledge-base/one-time-passwords) to a user. |

## Configuration Options

Before you can start sending messages you'll need to decide which approach you want to take to to implement message senders. There are three different configuration options ranging from least to most control. Please read the following sections for more detail.

### Default Sender

This is our no code option, and should only be used for testing purposes. It sends emails with OrderCloud's Mailchimp account as well as with our own templates. There is nearly no setup to get going but it also means there is no control over the email templates, sender, or subject line.

To enable this option:

1. [Create a new delivery config](https://api-docs.sitecore.com/ordercloud/delivery-configurations/deliveryconfigurations.create) with a Mailchimp delivery target and a null ApiKey

```json
1{
2  "Name": "test emails",
3  "Enabled": true,
4  "DeliveryTargets": {
5    "Mailchimp": {
6      "ApiKey": null
7    }
8  }
9}
```

1. [Create a new message sender](https://api-docs.sitecore.com/ordercloud/message-senders/messagesenders.create) with the DeliveryConfigID of the resource created above and the desired MessageTypes

2. [Assign the message sender](https://api-docs.sitecore.com/ordercloud/message-senders/messagesenders.saveassignment) to the relevant parties OR use `AllowAllBuyers` if you don't need explicit assignments


### Your Own Mailchimp Account

This is our low code option that gives you a bit more control - you are able to provide your own custom email templates but the actual sending of the emails is handled by OrderCloud. This option requires that you have your own [Mailchimp](https://mailchimp.com/features/transactional-email/) account.

To enable this option:

1. Create each of your email templates in Mailchimp. Refer to [this table](https://doc.sitecore.com/ordercloud/en/developers/platform/message-senders.html#custom-email-templates---mailchimp-merge-vars) to determine which variables are available to render in your email template

2. Name your templates so that they match MessageType exactly

      1. If you have a need for multiple templates for the same MessageType, for example you have multiple Buyer companies and need custom branding for their respective emails, you'll need to provide some custom configuration details in xp, which is explained below
      2. Your templates **must** include a subject and from email address
3. [Create a new delivery config](https://api-docs.sitecore.com/ordercloud/delivery-configurations/deliveryconfigurations.create) with a Mailchimp delivery target, include your ApiKey

4. [Create a new message sender](https://api-docs.sitecore.com/ordercloud/message-senders/messagesenders.create) with the DeliveryConfigID of the resource created above and the desired MessageTypes

5. [Assign the message sender](https://api-docs.sitecore.com/ordercloud/message-senders/messagesenders.saveassignment) to the relevant parties OR use `AllowAllBuyers` if you don't need explicit assignments


If you have multiple MessageSenders and need to override the template names, you'll need to include the following data in each MessageSender xp:

```http
1"xp": {
2    "MessageTypeConfig": [\
3      {\
4        "MessageType": "ForgottenPassword",\
5        "TemplateName": "ForgottenPassword-Buyer1"\
6      },\
7      {\
8        "MessageType": "NewUserInvitation",\
9        "TemplateName": "NewUserInvitation-Buyer1"\
10      }\
11    ]
12  }
```

### Custom URL

In this option you provide OrderCloud the URL to your publicly available endpoint that will receive the event payload and is responsible for formatting as well as sending the notification. As you can imagine this grants you the most amount of control but it also requires more work on your end to accomplish. Here are a few reasons you may decide to go down this path:

- You want to use a different messaging provider than Mailchimp

- You want to send more than just emails such as texts or maybe something else entirely

- You need your notifications to include data that isn't available in the normal event payload

- You need to add some additional business-specific decisioning logic when sending an email


To enable this option:

1. Create and host a custom endpoint to receive and process the event payload

2. [Create a new delivery config](https://api-docs.sitecore.com/ordercloud/delivery-configurations/deliveryconfigurations.create) with a MessageSender delivery target, include your custom `Endpoint` and optionally a `Secret`

3. [Create a new message sender](https://api-docs.sitecore.com/ordercloud/message-senders/messagesenders.create) with the DeliveryConfigID of the resource created above and the desired MessageTypes

4. [Assign the message sender](https://api-docs.sitecore.com/ordercloud/message-senders/messagesenders.saveassignment) to the relevant parties OR use `AllowAllBuyers` if you don't need explicit assignments


Creating the custom endpoint is going to be the most laborious part of implementing this option. To help you out we've created a [.NET starter project](https://github.com/ordercloud-api/MessageSender) that demonstrates how to handles these types of events and has examples for sending notifications from Mailchimp, Sendgrid, and Twilio. Check out the [payload models](https://doc.sitecore.com/ordercloud/en/developers/platform/message-senders.html#message-sender-event-payload-models) for each message type.

Here are a few other things to keep in mind as you're building your endpoint:

- We highly recommend validating every incoming requests against the `Secret` sent along with each request to your endpoint.

- Use the special variable `{messagetype}` in the custom URL provided to OrderCloud. This lets you define a single message sender configuration that can handle different message types. For example the custom url `https://my-message-handler/{messagetype}` that has opted in for an `OrderSubmitted` and `ForgottenPassword` message type will receive requests to the endpoint `https://my-message-handler/ordersubmitted` as well as `https://my-message-handler/forgottenpassword`.

- If your handler needs elevated permissions to complete its work you may consider defining `ElevatedRoles` this will grant your endpoint a token for the recipient user that additionally has any elevated roles defined. This can help simplify your logic especially if your handler is a one-off serverless function for example.

- Like most other entities in OrderCloud, Message Senders come with [extended properties](https://doc.sitecore.com/ordercloud/en/developers/platform/extended-properties.html) which you can use to store business specific data to drive custom behavior. Please note that xp will come through as `ConfigData` in the event payload.

- Check out our [default templates](https://github.com/ordercloud-api/mailchimp-email-templates/tree/master/Transactional) to use as a starting point.


## Custom Email Templates - Mailchimp Merge Vars

If you're using our Mailchimp integration and providing your own custom email templates then you can use these tables to determine which variables are available for you to render in your email templates.

### Variables for ForgottenPassword and NewUserInvitation

| Mailchimp Variable | OrderCloud Property |
| --- | --- |
| username | Username |
| passwordtoken | passwordtoken |
| passwordverification | passwordverificationcode |
| passwordrenewalurl | passwordrenewalurl |

### Variables for Order Emails

| Mailchimp Variable | OrderCloud Property |  |
| --- | --- | --- |
| firstname | Order.FromUser.FirstName |  |
| lastname | Order.FromUser.LastName |  |
| orderid | Order.ID |  |
| datesubmitted | Order.DateSubmitted |  |
| subtotal | Order.Subtotal |  |
| tax | Order.TaxCost |  |
| shipping | Order.ShippingCost |  |
| total | Order.Total |  |
| lineitemcount | Order.LineItemCount |  |
|  | Mailchimp Variable | OrderCloud Property |
|  | cost | LineItems\[i\].LineTotal |
|  | quantity | LineItems\[i\].Quantity |
|  | productdesc | LineItems\[i\].Product.Description |
|  | productid | LineItems\[i\].Product.ID |
|  | productname | LineItems\[i\].Product.Name |
| products (array) | shiptoname | LineItems\[i\].ShippingAddress.FirstName + LineItems\[i\].ShippingAddress.LastName |
|  | shiptostreet1 | LineItems\[i\].ShippingAddress.Street1 |
|  | shiptostreet2 | LineItems\[i\].ShippingAddress.Street2 |
|  | shiptocity | LineItems\[i\].ShippingAddress.City |
|  | shiptostate | LineItems\[i\].ShippingAddress.State |
|  | shiptopostalcode | LineItems\[i\].ShippingAddress.Zip |
|  | shiptocountry | LineItems\[i\].ShippingAddress.Country |
|  | Mailchimp Variable | OrderCloud Property |
|  | approvinggroupid | OrderApproval\[i\].ApprovingGroupID |
|  | status | OrderApproval\[i\].Status |
|  | datecreated | OrderApproval\[i\].DateCreated |
|  | datecompleted | OrderApproval\[i\].DateCompleted |
| approvals (array) | approverid | OrderApproval\[i\].Approver.ID |
|  | approveremail | OrderApproval\[i\].Approver.Email |
|  | approverfirstname | OrderApproval\[i\].Approver.FirstName |
|  | approverlastname | OrderApproval\[i\].Approver.LastName |
|  | approverusername | OrderApproval\[i\].Approver.Username |
|  | approverphone | OrderApproval\[i\].Approver.Phone |
|  | Mailchimp Variable |  |
| orderxp (array) | orderxp\_keyname | for first-level xp properties |
|  | orderxp\_keyname\_keyname | for nested xp properties |
|  | orderxp\_keyname\_index | for xp arrays |

### Variables for OrderReturn

Includes all of the variables for [order emails](https://doc.sitecore.com/ordercloud/en/developers/platform/message-senders.html#variables-for-order-emails) and additionally the following:

| Mailchimp Variable | OrderCloud Property |  |
| --- | --- | --- |
| orderreturnid | OrderReturn.ID |  |
| refundamount | OrderReturn.RefundAmount |  |
|  | Mailchimp Variable | OrderCloud Property |
| returnitems (array) | LineItemID | OrderReturn.ItemsToReturn\[i\].LineItemID |
|  | Quantity | OrderReturn.ItemsToReturn\[i\].Quantity |
|  | RefundAmount | OrderReturn.ItemsToReturn\[i\].RefundAmount |
|  | Mailchimp Variable |  |
| orderreturnxp (array) | orderreturnxp\_keyname | for first-level xp properties |
|  | orderreturnxp\_keyname\_keyname | for nested xp properties |
|  | orderreturnxp\_keyname\_index | for xp arrays |

### Variables for ShipmentCreated

Includes all of the variables for [order emails](https://doc.sitecore.com/ordercloud/en/developers/platform/message-senders.html#variables-for-order-emails) and additionally the following:

| Mailchimp Variable | OrderCloud Property |  |
| --- | --- | --- |
| shipmentid | Shipment.ID |  |
| shipmenttrackingnumber | Shipment.TrackingNumber |  |
| shipper | Shipment.Shipper |  |
| dateshipped | Shipment.DateShipped |  |
| toaddressid | Shipment.ToAddress.ID |  |
| toaddresscompany | Shipment.ToAddress.Company |  |
| toaddressfirstname | Shipment.ToAddress.FirstName |  |
| toaddresslastname | Shipment.ToAddress.LastName |  |
| toaddressstreet1 | Shipment.ToAddress.Street1 |  |
| toaddressstreet2 | Shipment.ToAddress.Street2 |  |
| toaddresscity | Shipment.ToAddress.City |  |
| toaddressstate | Shipment.ToAddress.State |  |
| toaddresspostalcode | Shipment.ToAddress.PostalCode |  |
| toaddresscountry | Shipment.ToAddress.Country |  |
| toaddressname | Shipment.ToAddress.AddressName |  |
|  | Mailchimp Variable | OrderCloud Property |
|  | cost | LineItem.LineTotal |
|  | quantityshipped | Shipment.Items\[i\].QuantityShipped |
| shipmentitems(array) | productdesc | Shipment.Items\[i\].Product.Description |
|  | productid | Shipment.Items\[i\].Product.ID |
|  | productname | Shipment.Items\[i\].Product.Name |

### Variables for OneTimePassword

| Mailchimp Variable | OrderCloud Property |
| --- | --- |
| username | Username |
| clientid | ClientID |
| onetimepassword | OneTimePassword |

## Message Sender Event Payload models

If you are building a custom message sender it is necessary to understand what kind of payloads your endpoint handler will receive. The first table lists properties common to all message types. The tables below that one are the event payloads specific to each message type.

### Generic Payload (not event specific)

| Property | Description |
| --- | --- |
| OcLogIdHeader | Internal log id |
| Environment | Maps to one of [OrderCloud's environments](https://doc.sitecore.com/ordercloud/en/developers/platform/regions-and-environments.html). Can be either Sandbox, Staging, or Production |
| BuyerID | ID of the buyer organization the user belongs to (if user is a buyer) |
| UserToken | Token of the recipient user, if ElevatedRoles is defined then the token will include those additional roles as well |
| Recipient | The full user object of the recipient user |
| CCList | The list of additional emails that will be CC'd for this message |
| EventBody | The specific event body for that message type (see below for each message type) |
| MessageType | The message type that this event was triggered for. Can be one of: NewUserInvitation, ForgottenPassword, OrderSubmitted, OrderSubmittedForApproval, OrderApproved, OrderDeclined, OrderSubmittedForYourApproval, OrderSubmittedForYourApprovalHasBeenApproved, OrderSubmittedForYourApprovalHasBeenDeclined, ShipmentCreated |
| ConfigData | This maps directly to any [extended properties](https://doc.sitecore.com/ordercloud/en/developers/platform/extended-properties.html) defined on the message sender |

### Event Body for ForgottenPassword and NewUserInvitation

| Property | Description |
| --- | --- |
| Username | The username of the user submitting the request |
| PasswordRenewalUrl | The URL passed in the original request |
| PasswordRenewalVerificationCode | The verification code to be passed when [resetting by verification code](https://api-docs.sitecore.com/ordercloud/forgotten-credentials/forgottencredentials.resetpasswordbyverificationcode) |
| PasswordRenewalAccessToken | The token of the user with only the role `PasswordReset` encoded. Used when [resetting password by token](https://api-docs.sitecore.com/ordercloud/me/me.resetpasswordbytoken) |

### Event Body for Order Events

| Property | Description |
| --- | --- |
| Order | The [order](https://api-docs.sitecore.com/ordercloud/orders/orders.get) that was submitted |
| Approvals | The array of [order approvals](https://api-docs.sitecore.com/ordercloud/orders/orders.listapprovals) for the order |
| LineItems | The array of [line items](https://api-docs.sitecore.com/ordercloud/line-items/lineitems.list) for the orders |
| Products | The array of [products](https://api-docs.sitecore.com/ordercloud/products/products.get) for the order |

### Event Body for OrderReturn Events

| Property | Description |
| --- | --- |
| Order | The [order](https://api-docs.sitecore.com/ordercloud/orders/orders.get) that was submitted |
| Approvals | The array of [order approvals](https://api-docs.sitecore.com/ordercloud/orders/orders.listapprovals) for the order |
| LineItems | The array of [line items](https://api-docs.sitecore.com/ordercloud/line-items/lineitems.get) for the orders |
| Products | The array of [products](https://api-docs.sitecore.com/ordercloud/products/products.get) for the order |
| OrderReturn | The [order return](https://api-docs.sitecore.com/ordercloud/order-returns/orderreturns.get) that was submitted |

### EventBody for ShipmentCreated

| Property | Description |
| --- | --- |
| Order | The [order](https://api-docs.sitecore.com/ordercloud/orders/orders.get) that was submitted |
| Approvals | The array of [order approvals](https://api-docs.sitecore.com/ordercloud/orders/orders.listapprovals) for the order |
| LineItems | The array of [line items](https://api-docs.sitecore.com/ordercloud/line-items/lineitems.get) for the orders |
| Products | The array of [products](https://api-docs.sitecore.com/ordercloud/products/products.get) for the order |
| Shipment | The [shipment](https://api-docs.sitecore.com/ordercloud/shipments/shipments.get) for the order |
| ShipmentItems | The array of [shipment items](https://api-docs.sitecore.com/ordercloud/shipments/shipments.getitem) for the shipment |

### Event Body for One-Time Passwords

| Property | Description |
| --- | --- |
| ClientID | The ID of the API Client that will be authenticated to |
| Username | The username of the user who will authenticate |
| OneTimePassword | The one-time password |

## Conclusion

You should now have a good understanding of what message senders are, how they differ from webhooks, and the different implementation options at your disposal.