SFMC Transactional Messaging

Salesforce Marketing Cloud is a provider of digital marketing automation and analytics software and services.

Send a transactional email, SMS, or push message from Salesforce Marketing Cloud to a single recipient as soon as Amperity sees the customer interaction, using the Transactional Messaging API . Each real-time point becomes one request for one recipient. Amperity sends the key of a transactional send definition that you create in Salesforce Marketing Cloud, the recipient, and attributes that the send definition can use for personalization.

Each destination sends on one channel: email, SMS, or push. To send on more than one channel, add one destination for each channel.

To enter a customer into a journey, use the SFMC Journey Builder connector; to write a row to a data extension, use the SFMC Data Extension Row connector. To load data extensions on a schedule rather than in real time, use the Salesforce Marketing Cloud destination.

This connector sends from a real-time journey. See Real-time destinations.

Requirements

  1. A transactional send definition for the destination’s channel must exist in Salesforce Marketing Cloud. This connector sends messages through a send definition; it does not create one.

  2. An installed package in Salesforce Marketing Cloud with an API integration that issues the client ID and client secret. This connector has no account ID setting, so Amperity does not name a business unit (MID) when it requests an access token, and the token covers the business unit that created the installed package. The send definition must be in that business unit.

Credentials

This connector uses the same credential type as the SFMC Journey Builder and SFMC Data Extension Row connectors. You can reuse one of those credentials here.

Name and description

The name and description for a credential.

API authentication subdomain

The authentication subdomain for your brand’s instance of the Marketing Cloud REST API.

Enter only the subdomain. The form shows “.rest.marketingcloudapis.com” after the field, and Amperity builds both the authentication host and the REST API host from the value you enter.

API client ID and client secret

The client ID and client secret for your brand’s instance of the Marketing Cloud REST API.

Settings

Name and description

The name and description for a destination.

Business user access

By default a destination is available to all users who have permission to view personally identifiable information (PII).

Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies.

Enable the PII setting checkbox to allow limited access to PII for this destination.

Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.

Channel

Required. The channel this destination sends on. May be “email”, “sms”, or “push”. The channel decides which send definitions the destination can use and which recipient attributes each send needs. See “Recipient attributes”, below.

Note

When you save the destination, Amperity tests the connection by listing the transactional send definitions for the selected channel. The test fails if the credentials are not valid or cannot read send definitions for that channel.

Activate node settings

The rest of the configuration for this connector belongs to the journey that sends to it. Add this destination to an Activate node, then configure the following on that node. Two nodes may send to the same destination with different send definitions and custom attributes. Mapped attributes are set once for the destination in the journey, so every node that sends to it uses the same mapped attributes.

definition-key

Required. On the Payload tab, the definition key of the transactional send definition that supplies the message. Amperity sends the key to the destination’s channel, so use a send definition for that channel.

Attribute names

On the Attributes tab, each Amperity attribute is sent under the destination attribute name it is mapped to. Destination attribute names may contain only letters, digits, hyphens, and underscores, and must be unique on the node. Names are matched exactly as written, so map “contact-key” and “to” in lowercase. A node needs at least one attribute.

Recipient attributes

Map Amperity attributes to these destination attribute names to identify the recipient:

  • contact-key is the subscriber’s contact key in Salesforce Marketing Cloud.

  • to is the recipient’s address: the email address for the email channel, or the phone number for the SMS channel.

Which attributes to map depends on the destination’s channel. The node’s attribute editor shows an error when the mapping does not match these rules:

Channel

Required attributes

email

contact-key. to is optional.

sms

contact-key and to.

push

contact-key or to, but not both.

Amperity sends contact-key and to exactly as mapped, without changing them. Amperity does not reformat phone numbers, so for the SMS channel the attribute mapped to to must already hold the phone number in the format Salesforce Marketing Cloud requires.

Amperity always sends a contact key. When contact-key has no value for a customer, including on the push channel when only to is mapped, the contact key is sent as null. to is left out of the request when it has no value.

Personalization attributes

Every other attribute mapped on the Attributes tab, and any custom attributes on the same node, is sent as a recipient attribute under the name it is mapped to. A custom attribute with the same name as a mapped attribute replaces it. Reference these names in the send definition’s content to personalize the message.

Values are sent as mapped, without changes, with these exceptions:

  • Date values are sent as text in “YYYY-MM-DD” format.

  • Datetime values are sent as text in ISO 8601 format, in UTC.

  • An attribute that is mapped but not on the customer’s profile is left out. An attribute on the profile with no value is sent as null.

Failed sends

Amperity makes up to three attempts at each send. Within an attempt, Amperity retries the request up to five times, with increasing waits, after a connection error, a request timeout (408), a rate limit error (429), or a server error (5xx). A send can therefore make up to 18 requests.

Amperity paces its requests to Salesforce Marketing Cloud at about one per second for each credential.

For the email and SMS channels, Amperity puts a message key in the request URL, and every request for a send, across retries and attempts, uses the same message key. Requests to the push channel carry no message key, so each of those requests is a separate push request.

Amperity classifies a failure by the text of the error from Salesforce Marketing Cloud first, and then by its HTTP status:

  • The error says “ObjectNotFound”. The send fails without another attempt, with the error from Salesforce Marketing Cloud. Check the definition-key and the destination’s channel.

  • 401 or 403. Amperity reports that Salesforce Marketing Cloud rejected the credential. The send fails without another attempt. Check the client ID, client secret, and subdomain. Amperity reuses its connection to Salesforce Marketing Cloud for each credential for up to 20 minutes, so after you edit the credential, sends can keep failing for up to 20 minutes. Choosing a different credential for the destination takes effect at once.

  • 400. The send fails without another attempt. Check the channel, the definition-key, and the attributes mapped on the Activate node.

  • 404, without “ObjectNotFound” in the error. Amperity makes another attempt, up to three in all.

  • Any other failure, including a 429 or server error that persists through the retries, and a connection error such as one caused by a wrong authentication subdomain, gets another attempt, up to three in all.

Amperity reports the send as successful when Salesforce Marketing Cloud accepts the request. Amperity does not check whether the message was delivered.