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:217

Accessors

MessageRetrieval

get MessageRetrieval(): MessageRetrievalCapabilities
Graph filters both of these server-side, so neither is emulated here — receivedDateTime comparisons and isRead are ordinary $filter clauses.

Returns MessageRetrievalCapabilities
Overrides BaseCommunicationProvider.MessageRetrieval
- Defined in providers/MSGraph/src/MSGraphProvider.ts:201

`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:1140

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:1254

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:1585

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:822

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:1121

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:1418

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:1236

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:1763

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:603

GetEvents

GetEvents(
params: GetEventsParams,
credentials?: MSGraphCredentials,
): Promise<GetEventsResult>
Reads calendar events for one mailbox.
Parameters
- params: GetEventsParams
- Optionalcredentials: MSGraphCredentials
Returns Promise<GetEventsResult>
Requires
MS Graph Scope: Calendars.Read (Application)

TWO ENDPOINTS, AND THE CHOICE IS VISIBLE TO THE CALLER. Graph exposes calendar data two ways and they do not return the same thing:
- /calendarView REQUIRES a start and end and EXPANDS recurring series into one entry per occurrence. A weekly stand-up in a two-week window comes back as two events, each with its own start time and id.
- /events needs no window and does NOT expand. That same stand-up is one row, the series master, whose start time is whenever the series began - possibly years ago.
A caller logging what actually happened wants occurrences; one asking "what meetings exist" may want masters. Silently picking would be a trap, because the two are indistinguishable by inspection - so the window decides, and RecurrenceExpanded on the result REPORTS which happened rather than leaving the caller to infer it.

CANCELLED EVENTS ARE EXCLUDED BY DEFAULT and cannot be recovered afterwards - Graph does not return them once filtered - so IncludeCancelled is honoured before the $top cap rather than by discarding rows after the fetch, which would silently shrink the page.
Overrides BaseCommunicationProvider.GetEvents
- Defined in providers/MSGraph/src/MSGraphProvider.ts:909

`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:779

`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:752

`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:663

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:490

`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:740

`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:710

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:1361

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:1343

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:1043

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:1715

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:1497

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:1552

`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:813

`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:790

`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:686

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:1462

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:1270

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:1194

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:431

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:1630

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:334

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:1152

Class MSGraphProvider

Remarks

Example

Hierarchy (View Summary)

Index

Constructors

Accessors

Methods

Constructors

constructor

Returns MSGraphProvider

Accessors

MessageRetrieval

Returns MessageRetrievalCapabilities

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

GetEvents

Parameters

Returns Promise<GetEventsResult>

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

`Protected`ProviderName

`Protected`GetHeaders

`Protected`GetHeadersWithClient

`Protected`GetHeadersWithEmail

`Protected`GetServiceAccount

`Protected`GetServiceAccountWithClient

`Protected`MarkMessageAsRead

`Protected`MarkMessageAsReadWithClient

`Protected`MarkMessageAsReadWithEmail