Two ways to send email from an orchestration

An orchestration can send email through the Workday Connect sendMessage REST API, which delivers to Workday workers using the tenant's notification setup, or through an email connector action, which sends from an outside mail account. Pick by who receives it: workers in the tenant, or anyone at any address.

The Developer Guide documents sendMessage as POST https://api.workday.com/connect/v1/sendMessage, and the call is made from an orchestration with the Send Workday API Request component. The connector route uses actions such as Send Email on the Gmail, Microsoft Outlook Email, Resend and Zoho Mail connectors, and Send Email or Send Templated Email on Amazon SES (Communication Connectors).

Workday's Developer Guide documents no separate Email REST API. The Connect API, which exposes sendMessage, message templates and notification types, is the documented Workday-native way to send, and version 2 of the Connect API keeps the same sendMessage operation.

What sendMessage needs before it will send

sendMessage is not a raw mail relay. It sends according to the tenant's Workday Notifications setup and routing rules, so the tenant must be configured first (Construct and Send Connect REST API Requests).

  1. Set up Workday Notifications on the tenant.
  2. In the Edit Tenant Setup - Notifications task, choose the notification type and its channels; Workday recommends Active Candidates, Learning Campaigns or Recruiting Marketing as the type. Under Notification Delivery Settings you select a Parent Notification Type and a Notification Type, then pick Default Notification Channels with the Override Notification Parent Type Settings check box. Immediate Email is the channel that delivers to an email client. Workday always also notifies My Tasks unless you select Disabled (Configure Your Tenant to Send Notifications).
  3. Give the account that calls the API the right security. The Send Message REST API is secured by the Administer Communications domain. Basic functionality also needs Set Up: Tenant Setup - BP and Notifications and Security Configuration, and each domain needs Report/Task: View and Modify (Security Domains for Connect Services). The request page also lists Set Up: Message Templates and Worker Data: Public Worker Reports as domains to configure as needed.

For how an integration system user is set up to call Workday APIs, see integration system users and API clients.

The request body

Workday's own example shows the shape. Send the body as JSON with a notificationType, the recipients and either inline content or a template:

{
  "notificationType": { "id": "<notification type Workday ID>" },
  "recipients": {
    "contacts": [
      { "id": "<worker Workday ID>" }
    ]
  },
  "emailDetail": {
    "name": "Equipment Services",
    "subject": "Your equipment request was approved",
    "body": "Your laptop request has been approved."
  }
}

The fields behave as follows.

  • emailDetail carries subject and body, which the API reference marks as required, plus optional name and replyTo.
  • pushDetail carries message for the Workday mobile app. You can send email and push in one request.
  • messageTemplate takes the Workday ID of a template created with the Message Template API or the Create Message Template task. Use it instead of emailDetail and pushDetail.
  • recipients.contacts holds Workday IDs. The API accepts Worker type contacts only. It returns an error for a candidate, student or other contact type.

To find a worker's Workday ID, use the Integration IDs > View IDs related action on the worker; you must be in the Developer security group. You can also look up the Notification Type ID with GET /notificationTypes in the Notification Type API.

The Connect API reference lists the reasons for a 400 response. At least one recipient is required. A message template cannot be supplied together with email or push details. A notification type is required and must match the template's. Version 2 adds that submitted Workday IDs must share one contact reference type, must be Worker type, and must be valid types. A 401 means missing or invalid credentials and a 403 means insufficient permissions.

Calling it with Send Workday API Request

In Orchestration Builder, add Send Workday API Request, which is available in the Synchronous, Asynchronous, Business Process, Home Card, Integration System and Custom Agent Action templates. Choose POST alongside the prepopulated Workday API address and complete the destination for /connect/v1/sendMessage. On the Auth tab choose an authentication type you created on the Credentials tab of the orchestration's Settings (Reference: Send Workday API Request).

On the Body tab you have two useful options. Reference Existing Data lets you build the body in a Create Values step and point to it in Expression Builder, with the Content Type set. Create Text Template lets you write the JSON as text with placeholders. The first is easier to keep correct when the recipient list is a loop result.

If the call fails, the status code and the step's error output are the first place to look; Workday Orchestrate errors and what they mean covers how to read them.

Sending to addresses outside Workday

sendMessage reaches workers, so it cannot send to a customer or a vendor contact. For an outside address use a connector action. On the Gmail, Microsoft Outlook Email, Resend and Zoho Mail connectors the action is Send Email, and Amazon SES also offers Send Templated Email, which fills template tags with values.

Workday documents connector actions for one place only: Custom Agent Actions orchestrations in an Extend Pro app. You add the connector on the app's Connectors tab and connect at least two service accounts, one for Production and one Default, which Orchestrate uses in Implementation and Sandbox tenants unless you add others (Add a Connector to an App). Then drag the Send Email action from the Connectors panel into the flow and pick the account under Connected Account (Add a Connector Action to an Orchestration). The documentation describes no connector route for Synchronous, Business Process or Integration System orchestrations, so plan on an HTTP call there.

For a mail service with a plain HTTP API, the alternative is the Send HTTP Request component, covered in calling external APIs from Orchestrate.

Proving the email was sent

A successful sendMessage call returns 201. Workday's sample response echoes the message and adds a commID object with a descriptor and an ID, so store that ID as the evidence that Workday accepted the message.

Accepted is not delivered. Check the recipient's side the way Workday suggests: the worker should see the message under Notifications in Workday, and an email in their inbox when Immediate Email is a channel for the notification type.

To test without mailing real people, add a row in General Email Notification Settings in Edit Tenant Setup - Notifications, select Redirect All Emails to Email Address and enter a test address. Every notification email the tenant sends, not only yours, then goes to that address (Configure Your Tenant to Send Notifications). Remove the row before the orchestration is used for real.

Sources checked