Class MSGraphProvider

Implementation of the MS Graph provider for sending and receiving messages.

Remarks

Microsoft Graph provides full mailbox access. This provider supports:

Sending messages
Fetching messages from inbox
Forwarding messages
Replying to messages
Creating drafts

Example

// Using environment credentials (default)
await engine.SendSingleMessage('Microsoft Graph', 'Standard Email', message);

// Using per-request credentials
await engine.SendSingleMessage('Microsoft Graph', 'Standard Email', message, undefined, false, {
    tenantId: 'customer-tenant-id',
    clientId: 'customer-client-id',
    clientSecret: 'customer-client-secret',
    accountEmail: 'customer@domain.com'
});

Hierarchy (View Summary)

BaseCommunicationProvider
- MSGraphProvider

Constructors

constructor

new MSGraphProvider(): MSGraphProvider
Returns MSGraphProvider
Overrides BaseCommunicationProvider.constructor
- Defined in providers/MSGraph/src/MSGraphProvider.ts:184

Accessors

`Protected`ProviderName

get ProviderName(): string
Returns the name of this provider for use in error messages. Override in subclasses to provide a more descriptive name.

Returns string
Inherited from BaseCommunicationProvider.ProviderName
- Defined in base-types/dist/BaseProvider.d.ts:986

SupportsPush

get SupportsPush(): boolean
Convenience gate: true when this provider supports inbound push in ANY form (subscription-managed or inbound-parse), false otherwise. Lets callers cleanly short-circuit — if (provider.SupportsPush) { ... } — instead of probing individual operations.

Derived from GetSubscriptionCapabilities so it stays in lockstep with actual capability: providers that support push return capabilities and thereby report SupportsPush === true for free; providers that don't return undefined and report false. Subclasses normally do NOT override this — override GetSubscriptionCapabilities instead.

Returns boolean
Inherited from BaseCommunicationProvider.SupportsPush
- Defined in base-types/dist/BaseProvider.d.ts:1083

Methods

ArchiveMessage

ArchiveMessage(
params: ArchiveMessageParams,
credentials?: MSGraphCredentials,
): Promise<ArchiveMessageResult>
Archives a message by moving it to the Archive folder using MS Graph.
Parameters
- params: ArchiveMessageParams
- Optionalcredentials: MSGraphCredentials
Returns Promise<ArchiveMessageResult>
Requires
MS Graph Scope: Mail.ReadWrite (Application)
Overrides BaseCommunicationProvider.ArchiveMessage
- Defined in providers/MSGraph/src/MSGraphProvider.ts:1354

CreateDraft

CreateDraft(
params: CreateDraftParams,
credentials?: MSGraphCredentials,
): Promise<CreateDraftResult>
Creates a draft email message via MS Graph.
Parameters
- params: CreateDraftParams
- Optionalcredentials: MSGraphCredentials
Returns Promise<CreateDraftResult>
Requires
MS Graph Scope: Mail.ReadWrite (Application)
Overrides BaseCommunicationProvider.CreateDraft
- Defined in providers/MSGraph/src/MSGraphProvider.ts:742

CreateSubscription

CreateSubscription(
params: CreateSubscriptionParams,
credentials?: MSGraphCredentials,
): Promise<SubscriptionResult>
Creates a Microsoft Graph change-notification subscription for messages in a mailbox folder. Graph validates the notification endpoint synchronously during this call (it must echo the validation token), so an unreachable/incorrect endpoint surfaces here as a Graph error.
Parameters
- params: CreateSubscriptionParams
  What to watch, where to notify, and the clientState secret
- Optionalcredentials: MSGraphCredentials
  Optional credentials override for this request
Returns Promise<SubscriptionResult>
Promise - Subscription ID and expiration on success

Requires
MS Graph Scope: Mail.Read (Application)
Overrides BaseCommunicationProvider.CreateSubscription
- Defined in providers/MSGraph/src/MSGraphProvider.ts:890

DeleteMessage

DeleteMessage(
params: DeleteMessageParams,
credentials?: MSGraphCredentials,
): Promise<DeleteMessageResult>
Deletes a message using MS Graph. If PermanentDelete is false, moves to Deleted Items folder.
Parameters
- params: DeleteMessageParams
- Optionalcredentials: MSGraphCredentials
Returns Promise<DeleteMessageResult>
Requires
MS Graph Scope: Mail.ReadWrite (Application)
Overrides BaseCommunicationProvider.DeleteMessage
- Defined in providers/MSGraph/src/MSGraphProvider.ts:1187

DeleteSubscription

DeleteSubscription(
params: DeleteSubscriptionParams,
credentials?: MSGraphCredentials,
): Promise<BaseMessageResult>
Deletes an existing Graph subscription. Idempotent from the consumer's perspective: a 404 (already gone) is treated as success. The caller MUST pass credentials for the same app registration that created the subscription.
Parameters
- params: DeleteSubscriptionParams
  The subscription ID to delete
- Optionalcredentials: MSGraphCredentials
  Optional credentials override for this request
Returns Promise<BaseMessageResult>
Promise - Result of the delete operation

Requires
MS Graph Scope: Mail.Read (Application)
Overrides BaseCommunicationProvider.DeleteSubscription
- Defined in providers/MSGraph/src/MSGraphProvider.ts:1005

DownloadAttachment

DownloadAttachment(
params: DownloadAttachmentParams,
credentials?: MSGraphCredentials,
): Promise<DownloadAttachmentResult>
Downloads an attachment from a message using MS Graph.
Parameters
- params: DownloadAttachmentParams
- Optionalcredentials: MSGraphCredentials
Returns Promise<DownloadAttachmentResult>
Requires
MS Graph Scope: Mail.Read (Application)
Overrides BaseCommunicationProvider.DownloadAttachment
- Defined in providers/MSGraph/src/MSGraphProvider.ts:1532

ForwardMessage

ForwardMessage(
params: ForwardMessageParams,
credentials?: MSGraphCredentials,
): Promise<ForwardMessageResult>
Forwards an email message via MS Graph.
Parameters
- params: ForwardMessageParams
- Optionalcredentials: MSGraphCredentials
Returns Promise<ForwardMessageResult>
Requires
MS Graph Scope: Mail.Send (Application)
Overrides BaseCommunicationProvider.ForwardMessage
- Defined in providers/MSGraph/src/MSGraphProvider.ts:524

`Protected`GetHeaders

GetHeaders(
    params: GetMessagesParams,
    user: { id?: string; userPrincipalName?: string },
    messageID: string,
): Promise<Record<string, string>>
Protected
Gets headers using default client.
Parameters
- params: GetMessagesParams
- user: { id?: string; userPrincipalName?: string }
- messageID: string
Returns Promise<Record<string, string>>
Requires
MS Graph Scope: Mail.Read (Application)
- Defined in providers/MSGraph/src/MSGraphProvider.ts:699

`Protected`GetHeadersWithClient

GetHeadersWithClient(
    client: Client,
    params: GetMessagesParams,
    user: { id?: string; userPrincipalName?: string },
    messageID: string,
): Promise<Record<string, string>>
Protected
Gets headers for a message using User object (requires prior user lookup). For better performance, consider using GetHeadersWithEmail() instead.
Parameters
- client: Client
- params: GetMessagesParams
- user: { id?: string; userPrincipalName?: string }
- messageID: string
Returns Promise<Record<string, string>>
Requires
MS Graph Scope: Mail.Read (Application)
- Defined in providers/MSGraph/src/MSGraphProvider.ts:672

`Protected`GetHeadersWithEmail

GetHeadersWithEmail(
    client: Client,
    emailAddress: string,
    params: GetMessagesParams,
    messageID: string,
): Promise<Record<string, string>>
Protected
Gets headers for a specific message using email address directly. This is the preferred method for new code as it avoids an extra API call to look up the user.
Parameters
- client: Client
- emailAddress: string
- params: GetMessagesParams
- messageID: string
Returns Promise<Record<string, string>>
Requires
MS Graph Scope: Mail.Read (Application)
- Defined in providers/MSGraph/src/MSGraphProvider.ts:583

GetMessages

GetMessages(
params: GetMessagesParams<Record<string, unknown>>,
credentials?: MSGraphCredentials,
): Promise<GetMessagesResult<Message>>
Retrieves email messages from a mailbox via MS Graph.
Parameters
- params: GetMessagesParams<Record<string, unknown>>
- Optionalcredentials: MSGraphCredentials
Returns Promise<GetMessagesResult<Message>>
Requires
MS Graph Scope: Mail.Read (Application), or Mail.ReadWrite if using ContextData.MarkAsRead option
Overrides BaseCommunicationProvider.GetMessages
- Defined in providers/MSGraph/src/MSGraphProvider.ts:429

`Protected`GetServiceAccount

GetServiceAccount(
email?: string,
): Promise<{ id?: string; userPrincipalName?: string }>
Protected
Gets the service account using default client. Caches the result for subsequent calls.
Parameters
- Optionalemail: string
Returns Promise<{ id?: string; userPrincipalName?: string }>
Requires
MS Graph Scope: User.Read.All (Application) - Required to look up user information
- Defined in providers/MSGraph/src/MSGraphProvider.ts:660

`Protected`GetServiceAccountWithClient

GetServiceAccountWithClient(
client: Client,
email: string,
): Promise<{ id?: string; userPrincipalName?: string }>
Protected
Gets the user account information by making an API call to MS Graph. This method looks up the full User object from the Graph API.
Parameters
- client: Client
- email: string
Returns Promise<{ id?: string; userPrincipalName?: string }>
Requires
MS Graph Scope: User.Read.All (Application) - Required to look up user information
- Defined in providers/MSGraph/src/MSGraphProvider.ts:630

GetSingleMessage

GetSingleMessage(
params: GetSingleMessageParams,
credentials?: MSGraphCredentials,
): Promise<GetSingleMessageResult>
Gets a single message by ID from MS Graph.
Parameters
- params: GetSingleMessageParams
- Optionalcredentials: MSGraphCredentials
Returns Promise<GetSingleMessageResult>
Requires
MS Graph Scope: Mail.Read (Application)
Overrides BaseCommunicationProvider.GetSingleMessage
- Defined in providers/MSGraph/src/MSGraphProvider.ts:1130

GetSubscriptionCapabilities

GetSubscriptionCapabilities(): SubscriptionCapabilities
Returns MS Graph's subscription capabilities. Graph mail subscriptions last at most 4230 minutes (~3 days), support all three change types, and require synchronous endpoint validation at create time.

Returns SubscriptionCapabilities
Overrides BaseCommunicationProvider.GetSubscriptionCapabilities
- Defined in providers/MSGraph/src/MSGraphProvider.ts:1112

getSupportedOperations

getSupportedOperations(): ProviderOperation[]
Returns the list of operations supported by MS Graph provider. MS Graph supports all mailbox operations.

Returns ProviderOperation[]
Overrides BaseCommunicationProvider.getSupportedOperations
- Defined in providers/MSGraph/src/MSGraphProvider.ts:813

ListAttachments

ListAttachments(
params: ListAttachmentsParams,
credentials?: MSGraphCredentials,
): Promise<ListAttachmentsResult>
Lists attachments on a message using MS Graph.
Parameters
- params: ListAttachmentsParams
- Optionalcredentials: MSGraphCredentials
Returns Promise<ListAttachmentsResult>
Requires
MS Graph Scope: Mail.Read (Application)
Overrides BaseCommunicationProvider.ListAttachments
- Defined in providers/MSGraph/src/MSGraphProvider.ts:1484

ListFolders

ListFolders(
params: ListFoldersParams,
credentials?: MSGraphCredentials,
): Promise<ListFoldersResult>
Lists mail folders using MS Graph.
Parameters
- params: ListFoldersParams
- Optionalcredentials: MSGraphCredentials
Returns Promise<ListFoldersResult>
Requires
MS Graph Scope: Mail.Read (Application)
Overrides BaseCommunicationProvider.ListFolders
- Defined in providers/MSGraph/src/MSGraphProvider.ts:1266

MarkAsRead

MarkAsRead(
params: MarkAsReadParams,
credentials?: MSGraphCredentials,
): Promise<MarkAsReadResult>
Marks messages as read or unread using MS Graph.
Parameters
- params: MarkAsReadParams
- Optionalcredentials: MSGraphCredentials
Returns Promise<MarkAsReadResult>
Requires
MS Graph Scope: Mail.ReadWrite (Application)
Overrides BaseCommunicationProvider.MarkAsRead
- Defined in providers/MSGraph/src/MSGraphProvider.ts:1321

`Protected`MarkMessageAsRead

MarkMessageAsRead(userID: string, messageID: string): Promise<boolean>
Protected
Marks a message as read using default client.
Parameters
- userID: string
- messageID: string
Returns Promise<boolean>
Requires
MS Graph Scope: Mail.ReadWrite (Application)
- Defined in providers/MSGraph/src/MSGraphProvider.ts:733

`Protected`MarkMessageAsReadWithClient

MarkMessageAsReadWithClient(
    client: Client,
    userID: string,
    messageID: string,
): Promise<boolean>
Protected
Marks a message as read using User ID. For better performance, consider using MarkMessageAsReadWithEmail() instead.
Parameters
- client: Client
- userID: string
- messageID: string
Returns Promise<boolean>
Requires
MS Graph Scope: Mail.ReadWrite (Application)
- Defined in providers/MSGraph/src/MSGraphProvider.ts:710

`Protected`MarkMessageAsReadWithEmail

MarkMessageAsReadWithEmail(
    client: Client,
    emailAddress: string,
    messageID: string,
): Promise<boolean>
Protected
Marks a message as read using email address directly. This is the preferred method for new code as it avoids an extra API call to look up the user.
Parameters
- client: Client
- emailAddress: string
- messageID: string
Returns Promise<boolean>
Requires
MS Graph Scope: Mail.ReadWrite (Application)
- Defined in providers/MSGraph/src/MSGraphProvider.ts:606

MoveMessage

MoveMessage(
params: MoveMessageParams,
credentials?: MSGraphCredentials,
): Promise<MoveMessageResult>
Moves a message to a different folder using MS Graph.
Parameters
- params: MoveMessageParams
- Optionalcredentials: MSGraphCredentials
Returns Promise<MoveMessageResult>
Requires
MS Graph Scope: Mail.ReadWrite (Application)
Overrides BaseCommunicationProvider.MoveMessage
- Defined in providers/MSGraph/src/MSGraphProvider.ts:1231

ParseNotification

ParseNotification(
input: WebhookNotificationInput,
_credentials?: MSGraphCredentials,
): Promise<ParseNotificationResult>
Parses and validates an inbound Graph change notification. Pure: no Graph client, no network. Safe on hostile/garbage input - never throws; returns Success: false with a 400 suggested status on malformed payloads.

Graph has no cryptographic signature scheme, so SignatureValid is left undefined; the consumer authenticates each notification by comparing its ClientState against the secret stored alongside the subscription.
Parameters
- input: WebhookNotificationInput
  Transport-neutral capture of the inbound webhook request
- Optional_credentials: MSGraphCredentials
Returns Promise<ParseNotificationResult>
Promise - Handshake or normalized notifications
Overrides BaseCommunicationProvider.ParseNotification
- Defined in providers/MSGraph/src/MSGraphProvider.ts:1039

RenewSubscription

RenewSubscription(
params: RenewSubscriptionParams,
credentials?: MSGraphCredentials,
): Promise<SubscriptionResult>
Renews an existing Graph subscription before it expires. The caller MUST pass credentials for the same app registration that created the subscription - Graph subscriptions are visible only to their creator, so a credential mismatch surfaces as a 404.
Parameters
- params: RenewSubscriptionParams
  The subscription ID and requested new expiration
- Optionalcredentials: MSGraphCredentials
  Optional credentials override for this request
Returns Promise<SubscriptionResult>
Promise - The renewed expiration on success

Requires
MS Graph Scope: Mail.Read (Application)
Overrides BaseCommunicationProvider.RenewSubscription
- Defined in providers/MSGraph/src/MSGraphProvider.ts:963

ReplyToMessage

ReplyToMessage(
params: ReplyToMessageParams,
credentials?: MSGraphCredentials,
): Promise<ReplyToMessageResult>
Replies to an email message via MS Graph.
Parameters
- params: ReplyToMessageParams
- Optionalcredentials: MSGraphCredentials
Returns Promise<ReplyToMessageResult>
Requires
MS Graph Scope: Mail.Send (Application)
Overrides BaseCommunicationProvider.ReplyToMessage
- Defined in providers/MSGraph/src/MSGraphProvider.ts:375

SearchMessages

SearchMessages(
params: SearchMessagesParams,
credentials?: MSGraphCredentials,
): Promise<SearchMessagesResult>
Searches messages using MS Graph search or filter.
Parameters
- params: SearchMessagesParams
- Optionalcredentials: MSGraphCredentials
Returns Promise<SearchMessagesResult>
Requires
MS Graph Scope: Mail.Read (Application)
Overrides BaseCommunicationProvider.SearchMessages
- Defined in providers/MSGraph/src/MSGraphProvider.ts:1399

SendSingleMessage

SendSingleMessage(
message: ProcessedMessage,
credentials?: MSGraphCredentials,
): Promise<MessageResult>
Sends a single email message via MS Graph.
Parameters
- message: ProcessedMessage
- Optionalcredentials: MSGraphCredentials
Returns Promise<MessageResult>
Requires
MS Graph Scope: Mail.Send (Application)
Overrides BaseCommunicationProvider.SendSingleMessage
- Defined in providers/MSGraph/src/MSGraphProvider.ts:275

supportsOperation

supportsOperation(operation: ProviderOperation): boolean
Checks if this provider supports a specific operation.
Parameters
- operation: ProviderOperation
  The operation to check
Returns boolean
true if the operation is supported
Inherited from BaseCommunicationProvider.supportsOperation
- Defined in base-types/dist/BaseProvider.d.ts:998

Class MSGraphProvider

Remarks

Example

Hierarchy (View Summary)

Index

Constructors

Accessors

Methods

Constructors

constructor

Returns MSGraphProvider

Accessors

ProtectedProviderName

Returns string

SupportsPush

Returns boolean

Methods

ArchiveMessage

Parameters

Returns Promise<ArchiveMessageResult>

Requires

CreateDraft

Parameters

Returns Promise<CreateDraftResult>

Requires

CreateSubscription

Parameters

Returns Promise<SubscriptionResult>

Requires

DeleteMessage

Parameters

Returns Promise<DeleteMessageResult>

Requires

DeleteSubscription

Parameters

Returns Promise<BaseMessageResult>

Requires

DownloadAttachment

Parameters

Returns Promise<DownloadAttachmentResult>

Requires

ForwardMessage

Parameters

Returns Promise<ForwardMessageResult>

Requires

ProtectedGetHeaders

Parameters

Returns Promise<Record<string, string>>

Requires

ProtectedGetHeadersWithClient

Parameters

Returns Promise<Record<string, string>>

Requires

ProtectedGetHeadersWithEmail

Parameters

Returns Promise<Record<string, string>>

Requires

GetMessages

Parameters

Returns Promise<GetMessagesResult<Message>>

Requires

ProtectedGetServiceAccount

Parameters

Returns Promise<{ id?: string; userPrincipalName?: string }>

Requires

ProtectedGetServiceAccountWithClient

Parameters

Returns Promise<{ id?: string; userPrincipalName?: string }>

Requires

GetSingleMessage

Parameters

Returns Promise<GetSingleMessageResult>

Requires

GetSubscriptionCapabilities

Returns SubscriptionCapabilities

getSupportedOperations

Returns ProviderOperation[]

ListAttachments

Parameters

Returns Promise<ListAttachmentsResult>

`Protected`ProviderName

`Protected`GetHeaders

`Protected`GetHeadersWithClient

`Protected`GetHeadersWithEmail

`Protected`GetServiceAccount

`Protected`GetServiceAccountWithClient

`Protected`MarkMessageAsRead

`Protected`MarkMessageAsReadWithClient

`Protected`MarkMessageAsReadWithEmail