MS Outlook – Messages – Create Message

Create an Outlook draft message. Uses the selected mailbox and returns the available result.

Creates a draft; it does not send mail. Retain the returned ID, add attachments if needed, then use MS Outlook – Messages – Send Message. Leave Is Draft unset or set it to true; setting it to false is not a send operation. The action requests Prefer: IdType="ImmutableId" for the creation response.

Action details

Property	Value
Action label	MS Outlook – Messages – Create Message
Category	CloudTools
Apex class and method	CreateMSOutlookMessage.createMessage
Input type	CreateMSOutlookMessage.CreateMSOutlookMessageInput
Output type	List<MSOutlookMessage>
Authorization	OAuth Delegated (Authorization Code) or OAuth Application (Client Credentials).
Flow automation	Use an application connector configured as the Flow default.
Microsoft Graph operation	POST /v1.0/me/messages for Authorization Code Flow; otherwise POST /v1.0/users/{userIdOrPrincipalName}/messages.

Prerequisites and permissions

Configure a CloudTools Connector with Connector Type set to Microsoft 365. Complete Microsoft sign-in for delegated access. For application access, grant application permissions and administrator consent, supply the target mailbox user ID or principal name, and ensure the app can access that mailbox.

Microsoft requires Mail.ReadWrite for delegated and application access. See the Microsoft operation and permissions reference.

Mailbox selection: Authorization Code Flow uses /me and ignores userIdOrPrincipalName. Supplying another user does not redirect that call. Other authorization types use /users/{userIdOrPrincipalName}; their authentication must be valid for Microsoft Graph. Use Graph resource IDs rather than Salesforce record IDs.

Inputs

The table lists action labels, Apex field names, and data types. Provide one non-null request per invocation. Required text must not be blank.

Input	Apex field	Type	Required	Description
User Id or Principal Name	userIdOrPrincipalName	String	Unless Authorization Code Flow is enabled	User id or user principal name. Required for application authorization; ignored for Authorization Code Flow.
Subject	subject	String	No	Message subject.
Body Content	bodyContent	String	No	Message body content.
Body Content Type	bodyContentType	String	No	Message body content type (Text/HTML). Defaults to Text when body content is supplied and this value is blank. A blank bodyContent omits the body entirely.
To Recipients CSV	toRecipientsCsv	String	No	Comma-separated to recipient addresses. Separate plain email addresses with commas. CloudTools trims whitespace and skips empty entries; it does not parse display-name address syntax.
Cc Recipients CSV	ccRecipientsCsv	String	No	Comma-separated cc recipient addresses. Separate plain email addresses with commas. CloudTools trims whitespace and skips empty entries; it does not parse display-name address syntax.
Bcc Recipients CSV	bccRecipientsCsv	String	No	Comma-separated bcc recipient addresses. Separate plain email addresses with commas. CloudTools trims whitespace and skips empty entries; it does not parse display-name address syntax.
Importance	importance	String	No	Message importance (low/normal/high).
Is Draft	isDraft	Boolean	No	Whether this message is draft.

The invocable input has no connectorId field. Apex and Flow use CloudTools connector selection; the LWC controller accepts an additional connectorId property to select a record. This action does not resolve replacement tokens in its inputs; resolve dynamic values first. See Using Token Replacements.

Outputs

Returns a list containing one MSOutlookMessage, or an empty list if no response is mapped. Check the returned ID before subsequent operations.

Output	Apex field	Type	Description
Id	id	String	Message identifier.
Subject	subject	String	Message subject.
Body Preview	bodyPreview	String	Message body preview.
Body	body	MSOutlookMessageItemBody	Message body.
From	fromRecipient	MSOutlookMessageRecipient	From recipient.
Sender	senderRecipient	MSOutlookMessageRecipient	Sender recipient.
To Recipients	toRecipients	List<MSOutlookMessageRecipient>	Recipient collection.
Cc Recipients	ccRecipients	List<MSOutlookMessageRecipient>	CC recipient collection.
Bcc Recipients	bccRecipients	List<MSOutlookMessageRecipient>	BCC recipient collection.
Reply To	replyTo	List<MSOutlookMessageRecipient>	Reply-to recipient collection.
From Address	fromAddress	String	From email address.
Sender Address	senderAddress	String	Sender email address.
To Recipients	toRecipientsCsv	String	Comma-separated recipients.
Cc Recipients	ccRecipientsCsv	String	Comma-separated CC recipients.
Bcc Recipients	bccRecipientsCsv	String	Comma-separated BCC recipients.
Received Date Time	receivedDateTime	String	Received timestamp.
Sent Date Time	sentDateTime	String	Sent timestamp.
Created Date Time	createdDateTime	String	Created timestamp.
Last Modified Date Time	lastModifiedDateTime	String	Last modified timestamp.
Parent Folder Id	parentFolderId	String	Parent folder identifier.
Internet Message Id	internetMessageId	String	Internet message identifier.
Web Link	webLink	String	Outlook web link.
Is Draft	isDraft	Boolean	Whether message is draft.
Has Attachments	hasAttachments	Boolean	Whether message has attachments.
Importance	importance	String	Message importance.
Conversation Id	conversationId	String	Conversation identifier.
Conversation Index	conversationIndex	String	Conversation index.
Follow Up Flag	followUpFlag	MSOutlookMessageFollowupFlag	Follow-up metadata.
Attachments	attachments	List<DynamicObject>	Message attachments.
Extensions	extensions	List<DynamicObject>	Message extensions.
OData Type	odataType	String	OData type.
OData ETag	odataEtag	String	OData etag.
Additional Properties	additionalProperties	List<DynamicObject>	Additional data returned by query.

Optional properties depend on the response and any Select or Expand query. Do not treat an absent field as proof of its value. Timestamps represented by String remain text. Nested body and recipient properties follow the Apex message model; content, recipient collections, and attachment expansion are not guaranteed.

In the Apex model, Body exposes content and contentType. Each recipient exposes emailAddress.address and emailAddress.name. Follow Up Flag exposes flagStatus, startDateTime, dueDateTime, and completedDateTime; each date object has dateTime and timeZone. Availability depends on response mapping. Use the top-level id for Graph message operations, rather than internetMessageId or conversationId.

Use in Flow

Add MS Outlook – Messages – Create Message in Flow Builder. Configure a Microsoft 365 application connector as the default for Flow automations, then populate the inputs above. Delegated connectors are not supported for CloudTools Flow automation. Add a fault path for callout errors. This implementation processes only the first input request; it is not a bulk action.

Use in custom Apex

This subscriber-org example uses the Apptigent namespace. Replace placeholders before use. Run in a context that permits callouts with a configured application connector. For an already-authorized delegated connector, omit the user value.

Apptigent.CreateMSOutlookMessage.CreateMSOutlookMessageInput request =
    new Apptigent.CreateMSOutlookMessage.CreateMSOutlookMessageInput();
request.userIdOrPrincipalName = 'REPLACE_WITH_MICROSOFT_USER_ID_OR_UPN';
request.subject = 'Project update';
request.bodyContent = 'Here is the project update.';
request.bodyContentType = 'Text';
request.toRecipientsCsv = 'recipient@example.com';
request.isDraft = true;

List<Apptigent.MSOutlookMessage> results =
    Apptigent.CreateMSOutlookMessage.createMessage(
        new List<Apptigent.CreateMSOutlookMessage.CreateMSOutlookMessageInput>{ request }
    );

Apptigent.MSOutlookMessage item = results.isEmpty() ? null : results[0];
String resultId = item == null ? null : item.id;
System.debug(resultId);

Submit one request per invocation. The example does not implement connector setup, delegated sign-in, or exception handling; those belong in the calling application.

Use in a Lightning Web Component

Use createMSOutlookMessage from msOutlookConnectorLib, through MSOutlookConnectorController. This example uses repository c/ imports for a component in the same namespace. Replace placeholders and complete connector authorization before invoking it.

outlookActionExample.js

import { LightningElement } from 'lwc';
import { createMSOutlookMessage, MSOutlookObjects } from 'c/msOutlookConnectorLib';

export default class OutlookActionExample extends LightningElement {
    connectorId = 'REPLACE_WITH_CONNECTOR_RECORD_ID';
    result = null;
    errorMessage = '';
    isRunning = false;
    completed = false;

    async handleRun() {
        if (this.isRunning || this.completed) {
            return;
        }
        this.isRunning = true;
        this.errorMessage = '';
        try {
            const request = MSOutlookObjects.inputs.message();
            request.connectorId = this.connectorId;
            request.userIdOrPrincipalName = 'REPLACE_WITH_MICROSOFT_USER_ID_OR_UPN';
            request.subject = 'Project update';
            request.bodyContent = 'Here is the project update.';
            request.bodyContentType = 'Text';
            request.toRecipientsCsv = 'recipient@example.com';
            request.isDraft = true;
            const result = await createMSOutlookMessage(request);
            if (!result?.id) {
                throw new Error('No resource ID was returned.');
            }
            this.result = result;
            this.completed = true;
        } catch (error) {
            this.errorMessage = error.requiresInteractiveAuthorization
                ? 'Sign in to Microsoft for this connector, then try again.'
                : error.message || 'The Outlook action failed.';
        } finally {
            this.isRunning = false;
        }
    }
}

outlookActionExample.html

<template>
    <lightning-button label="Run action" onclick={handleRun}
        disabled={isRunning}></lightning-button>
    <p role="alert">{errorMessage}</p>
</template>

The library accepts one request object and resolves to one resource object, or null when no response is mapped; read result.id directly. The shared factory includes inputs for other actions; only the fields in this page and optional connectorId are used here.

The LWC controller flattens body into bodyContent and bodyContentType, recipients into address and CSV fields including replyToRecipientsCsv, and follow-up metadata into flag status and date fields. Use the JavaScript response shape rather than assuming the nested Apex fields are present. The response also exposes rawJson, which is not an invocable Flow output and may be a serialization of the mapped model.

This example reports authorization errors but does not implement sign-in. For delegated access, use getMSOutlookAuthorizationState, beginMSOutlookAuthorization, and createMSOutlookOAuthMessageHandler. Errors expose message and requiresInteractiveAuthorization.

The example prevents another invocation after success. Reset completed only when deliberately starting a new operation. If an error leaves the outcome uncertain, verify mailbox state before retrying; repeating the action can create duplicate mail, attachments, or folders, or act on an item that has already moved or been deleted.

Error handling and troubleshooting

Symptom	What to check
Required fields error	Pass a nonempty list with a non-null first request. Populate required resource fields and User Id or Principal Name for application authorization.
Authorization is required	Complete or renew the current user’s delegated Microsoft authorization for the selected connector.
Access denied	Check the operation permission, consent, connector identity, and mailbox access.
Resource not found	Verify IDs belong to the selected mailbox and refer to the expected resource. Authorization Code Flow ignores the user input.
Operation rejected	Review the Microsoft error and confirm the resource supports this operation.
Unexpected result	Check for an empty Apex result, a null JavaScript response, omitted properties, or incomplete pagination. Handle exceptions in the caller.