Getting started with Sunsetless EWS

From the package swap to the first call on Microsoft Graph. Your EWS code does not change.

  1. Check that it fits your application

    Pick the package for your EWS library. Both run on .NET Framework and on .NET 8, 9 and 10.

    Your code usesInstall from NuGet.org
    Microsoft.Exchange.WebServicesMicrosoft's EWS Managed APISunsetless.Ews
    Microsoft.Exchange.WebServices.NETStandardThe community port with the async APISunsetless.Ews.NETStandard
    Microsoft.Exchange.WebServices.dll Loaded in a PowerShell script, see EWS scripts in PowerShellSunsetless.Ews

    To see whether every call your code makes is covered, run your usage report through the usage checker, which also sets apart the Microsoft and vendor apps in the report, or look up single operations in the compatibility table.

  2. Swap the package

    Replace the Microsoft package with ours from NuGet.org and rebuild. Your code compiles unchanged.

    dotnet remove package Microsoft.Exchange.WebServices
    dotnet add package Sunsetless.Ews

    On the .NET Standard port, swap that package instead. Your await calls stay as they are.

    dotnet remove package Microsoft.Exchange.WebServices.NETStandard
    dotnet add package Sunsetless.Ews.NETStandard

    On .NET Framework 4.6.2 and newer the package's dependencies need assembly binding redirects. Set <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects> in the application's project and the build writes them to the application's .exe.config. A web application reads them from web.config, which the build does not change: add the redirects there by hand. A missing redirect shows as Could not load file or assembly 'System.Memory, ...'.

    A project that targets .NET Framework 3.5 to 4.6.1 gets a Microsoft.Exchange.WebServices.dll without dependencies and needs no redirects. Calls to Exchange Online then need .NET Framework 4.7.2 or newer on the computer. An application built for .NET Framework 3.5 must also run on the .NET Framework 4 runtime: put <supportedRuntime version="v4.0" /> first in the <startup> section of its .exe.config.

  3. Grant Graph permissions

    Register an app in Microsoft Entra ID, or use the one you have, and grant it the Microsoft Graph application permissions your code needs:

    Mail.ReadWrite, Mail.Sendmail, mail folders, search folders, conversations, sync and notifications
    Calendars.ReadWritecalendars, meetings, availability and delegates
    Contacts.ReadWrite (or Contacts.Read to only read)contacts, contact pictures, contact folders, FindPeople in a contact folder
    Tasks.ReadWrite.Alltasks
    MailboxSettings.ReadWriteout-of-office settings, inbox rules, categories and working hours
    User.Read.All, Group.Read.AllResolveNames, ExpandDL, FindPeople in the directory, user photos
    ProfilePhoto.ReadWrite.AllSetUserPhoto
    Place.Read.Allroom lists

    Seven more permissions are optional. Without them the rest works, and the operations that need them return a clear error that names the permission:

    MailboxFolder.Read.Allfolders of every kind in folder listings; calendars created through EWS before the switch; Notes and Journal; a person's contacts in hidden folders for FindPeople
    MailboxFolder.ReadWrite.Allrenaming, moving, copying and deleting calendars created through EWS
    MailboxItem.Read.Allcontact groups, a task's companies and contacts, non-mail items in Deleted Items and Recoverable Items
    MailboxItem.ImportExport.All what Graph has no call of its own for, such as ArchiveItem, moving and copying contacts, tasks and calendar items, meetings saved with SendToNone, posts and contact groups
    MailboxItem.ReadWrite.Alldeleting contacts and contact groups in a single call, and purging a contact group from Recoverable Items
    MailboxConfigItem.ReadWriteuser configuration objects of every name and the retention policy tags, through a Microsoft Graph API still in preview
    Mail-Advanced.ReadWrite.All changing the subject, body, recipients or extended properties of received and sent messages, which Microsoft Graph requires from 31 December 2026
    Domain.Read.AllAutodiscover GetDomainSettings
  4. Set the configuration

    Nothing changes in your code. Set these environment variables for the process:

    SUNSETLESS_TENANT_ID=<your Entra tenant ID>
    SUNSETLESS_CLIENT_ID=<the application (client) ID of the app registration>
    SUNSETLESS_CLIENT_SECRET=<a client secret of the app registration>
    SUNSETLESS_LICENSE_KEY=<your trial or license key>

    Microsoft recommends a certificate for production: leave SUNSETLESS_CLIENT_SECRET out and set SUNSETLESS_CERT_THUMBPRINT (a certificate in the Windows certificate store), or SUNSETLESS_CERT_PATH and SUNSETLESS_CERT_PASSWORD (a .pfx file).

    One process that works for several tenants, such as a hosted product, configures each ExchangeService in code instead, with SunsetlessEws.Configure(service, options).

    Calls to Exchange Server keep using EWS. If your application still calls an Exchange Server URL after its mailboxes moved to Exchange Online, set SUNSETLESS_BRIDGE_ALL_HOSTS=true and every host goes to Microsoft Graph.

    No key yet? Get a free trial key for your tenant. The README in the package lists the optional settings and the configuration in code.

  5. Limit mailbox access

    Scope the app to the mailboxes it uses with RBAC for Applications in Exchange Online. That decision is made in your tenant; the library does not make it for you.

  6. Test with your own mailboxes

    Run your normal workflows against a test mailbox. Pay attention to the areas the compatibility table marks with differences, such as notifications, tasks and delegates.

    Runnable samples for .NET 8, .NET Framework 4.8 and .NET Framework 3.5, for a process that serves several tenants and for a component that ships the library, are in the samples repository on GitHub. Report anything that behaves differently from EWS in its issue tracker.