Skip to main content

Microsoft 365

tc.m365 reads Excel files and SharePoint lists and sends Outlook mail as the signed-in user, through the Integration Gateway. People only see files they can already open in SharePoint or OneDrive. That's deliberate: the app never widens anyone's access.

  • Browser: works as is.
  • Server: pass { request: req } (Python: request=request) or use tc.middleware().
  • Jobs (cron and worker services) act as the app. Graph is then limited to the sites and files IT granted (Sites.Selected), and mail goes from the project owner.

tc.m365.excel(url, options)​

Opens an Excel workbook in SharePoint or OneDrive.

tc.m365.excel(url: string, opts?: { sheet?: string; request?: RequestLike; as?: 'user' | 'project' }): ExcelWorkbook
ParameterTypeDescription
urlstringThe file's address, or its "Copy link" sharing link
opts.sheetstringDefault sheet for range()
opts.requestRequestLikeServer: the incoming request
opts.as'user' | 'project'Server: 'project' forces the app identity

Returns an ExcelWorkbook. Nothing is fetched until you call a method.

MethodReturns
info(){ id, driveId, name, webUrl, lastModifiedDateTime, lastModifiedBy }
tables(){ id, name }[]
worksheets(){ id, name }[] (JavaScript only)
table(name)An ExcelTable
range(address, { sheet })An ExcelRange. address is A1:C10 or Sheet!A1:C10; without a sheet, the first sheet is used.

ExcelTable

MethodReturns
rows()Rows as objects keyed by the table's header row
values()Raw 2-D array, header row first
columns()Header names
dataframe()Python only: a pandas DataFrame

ExcelRange

MethodReturns
values()Raw 2-D array
rows()Objects keyed by the first row
tip

Prefer Excel tables over ranges: a table keeps working when people add rows.

Errors

CodeWhenFix
M365_BAD_URLThe URL isn't an http(s) SharePoint/OneDrive address
M365_ACCESS_DENIEDThe signed-in user can't open the fileAsk the file's owner to share it. To show the data to everyone who can open the app, the owner asks once (console → Integrations → "Show data to everyone with app access", or MCP request_grant with share_file).
M365_NOT_FOUNDNo such fileCopy the address from SharePoint
M365_TABLE_NOT_FOUND, M365_SHEET_NOT_FOUNDWrong table or sheet nameCheck Table Design → Table Name, or the sheet tab
UNAUTHENTICATEDNo signed-in userReload; on the server pass the request
ACCESS_PENDING, ACCESS_DENIEDThe gateway refused before Graph was calledSee Integrations
M365_ERRORAny other Graph error
const url = 'https://contoso.sharepoint.com/sites/Finance/Shared Documents/Budget FY27.xlsx'

const rows = await tc.m365.excel(url).table('Actuals').rows()
// → [{ 'Cost Center': 'CC-2100', Month: 'Jul 2026', Actual: 95400 }, …]

const cells = await tc.m365.excel(url).range('Summary!A1:B6').values()

// Server
const budget = await tc.m365.excel(url, { request: req }).table('Budget').rows()

tc.m365.list(siteUrl, listName, options)​

A SharePoint list.

tc.m365.list(siteUrl: string, listName: string, opts?: { top?: number; request?: RequestLike; as?: 'user' | 'project' }): SharePointList
ParameterTypeDescription
siteUrlstringThe site, e.g. https://contoso.sharepoint.com/sites/Procurement
listNamestringList name or id
opts.topnumberMaximum items
MethodReturns
info(){ id, name, displayName }
items({ top })Items as objects: { id, Title, …fields }

Errors: M365_BAD_URL (not a …/sites/<name> URL), plus the Excel errors above.

const vendors = await tc.m365.list('https://contoso.sharepoint.com/sites/Procurement', 'Vendors').items()

tc.m365.mail.send(message)​

Sends an Outlook message as the signed-in user (saved to Sent Items). In jobs, it sends as the app from the project owner's mailbox.

tc.m365.mail.send(m: {
to: string | string[] | { address: string; name?: string }[]
cc?: string | string[]
subject: string
html?: string
text?: string
from?: string // jobs only; default TC_PROJECT_OWNER_EMAIL
request?: RequestLike
as?: 'user' | 'project'
}): Promise<{ sent: true }>

Errors: BAD_MAIL (missing to or subject), NO_SENDER (as the app without an owner email), plus Graph errors.

await tc.m365.mail.send({ to: 'someone@contoso.com', subject: 'Weekly report', html })

Raw Graph calls​

For anything else in Microsoft Graph, use tc.int.graph, for example tc.int.graph.get('/me'). Paths without /v1.0 get it added.

Was this page helpful?