Migrate from Microsoft Teams to Mattermost

How to migrate from Microsoft Teams to Mattermost without losing the history that matters

If your renewal, licensing change or residency requirement is pushing chat off Microsoft Teams, the short answer is that Teams chat and channel history can be exported through the Microsoft Graph Teams Export APIs and loaded into Mattermost, but integrations, bots and some content will need to be rebuilt by hand. The export side depends on admin-approved application permissions and an active Teams license on every user whose content is exported, so confirm license status for former employees and departed guests before you start, because a missing license blocks their history. Most organizations run this with an internal platform or IT team that owns the tenant, the Mattermost hosting and the cutover decisions, and bring in an implementation partner for the export tooling, the conversion scripts and the import runs. Effort depends on how much history you keep, how many teams and channels you map, and how many integrations sit on top of Teams. Ask any partner for a written scope that lists each of those inputs before agreeing to a timeline.

Pick the Mattermost edition before you build anything, because it determines what you can run. Team Edition is free and self-hosted, and Mattermost positions it for teams under 250 users that do not need single sign-on. If your Entra ID sign-on, directory sync or high availability is a requirement, you need a paid plan: SSO (SAML, OIDC and OAuth) and AD/LDAP sync start at Professional, while high availability clustering starts at Enterprise. Confirm the current tier boundaries on the Mattermost editions page, since these are the features that most often change the cost of the project. The Mattermost high availability documentation also requires shared file storage on each node, so a clustered deployment needs an S3-compatible store or NAS planned from the start rather than added at cutover.

The import itself is a conversion project. Mattermost's documented migration path converts a Slack export with mmetl into its bulk import format and loads it with mmctl, and Teams has no equivalent first-party importer, so your team writes or adapts a converter from the Graph export output. Test the converter on one team with a few channels, check threads, attachments and user mapping by hand, and only then run the full history. Decide up front which history is worth loading, since older messages add conversion and storage work for little operational value. Plan a manual rebuild for bots, connectors, custom emoji and Teams-specific apps, and confirm user identity mapping against your Entra ID accounts so that people appear under the right names when they log in.

Which Teams chat capabilities map to Mattermost and which need rework

This table compares each Teams chat capability with its Mattermost equivalent and marks it as clean, needs rework or gap. Clean means the history can move with little reshaping, needs rework means the export must be converted or the setup rebuilt, and gap means Mattermost chat does not cover it. Meetings, recordings and transcripts sit outside Mattermost, so plan a separate video service from the start.

Capability	Status	What it means for the migration
Channels and teams	Needs rework	Teams and channels must be rebuilt as Mattermost teams and channels in the import file.
Private channels	Needs rework	Confirm which admins can approve export of private channel history, then recreate membership in Mattermost.
1:1 and group chats	Needs rework	Graph exports these messages, but participants must be mapped to existing Mattermost accounts before loading.
Threads and replies	Needs rework	Replies must be linked to their parent posts in the converted file, or threads flatten into the channel.
File attachments	Needs rework	Confirm whether the export returns file content or links, then plan how files are uploaded to Mattermost storage.
Meeting recordings and transcripts	Gap	Mattermost is chat only. Keep recording links as archived content and use a separate video service.
Entra ID single sign-on	Gap	SSO through SAML or OIDC requires the Professional plan or higher, not the free Team Edition.
Retention	Needs rework	Set retention in Mattermost before cutover. Entry caps channel history at 10,000 messages.
Compliance export	Gap	Compliance export is available only in the paid Professional, Enterprise and Enterprise Advanced plans.
Bots, apps and connectors	Gap	Teams apps and connectors do not transfer. Rebuild each integration as a Mattermost integration.

What the Teams export returns and what must be rebuilt by hand

The Teams Export APIs move chat and channel history out of Microsoft Teams, but they do not recreate the workspace around it. The cards below separate what arrives in the export from what your team must confirm, convert and rebuild before Mattermost users can work in it.

Message types the export covers

The Graph Teams Export APIs return 1:1, group, meeting and channel messages, along with meeting recording and transcript links. Recordings and transcripts come back as links rather than as files loaded into Mattermost, so decide whether they stay in Microsoft 365 or move to your own file store. Confirm which message types your tenant actually returns before you plan the import volume.

Admin-approved application permissions

The export runs with application permissions that a Microsoft 365 administrator must approve in Entra ID. Ask your tenant administrator to confirm the exact permission set and consent path in writing before the project starts, because an unapproved scope stops the export partway through a tenant. Record who granted consent and when, since auditors often ask for that evidence.

Active Teams licenses on exported users

Every user whose messages you export must hold an active Teams license at the time of export. Users who have left the company or dropped Teams may already be unlicensed, which means their chat history may be missing from the output. Build a list of former staff and check it against the license report before you start, so that gaps are documented instead of discovered after cutover.

Identities mapped from Entra ID

Mattermost needs a user record for each person whose messages it imports, and the bulk import format references users by username and email. Map Entra ID object identifiers and user principal names to Mattermost accounts before loading, and decide how duplicate display names and shared mailboxes are handled. Single sign-on through SAML or OIDC is a separate configuration step that the import does not perform.

Channels and team membership

Teams channels, private channels and team membership do not carry over one to one into Mattermost teams and channels. Decide which Teams teams become Mattermost teams, which channels stay public, and which private channels need equivalent membership. Confirm the mapping with your converter, because the bulk import format expects channels and memberships to be declared explicitly.

Bots, tabs and integrations to rebuild

Teams apps, bots, connectors, tabs and Power Automate flows do not transfer into Mattermost. Inventory every app installed in your teams, identify which ones post messages or hold business data, and plan a replacement webhook or integration for each. Mattermost supports incoming and outgoing webhooks, but each one must be recreated and tested by hand.

The migration sequence from inventory to decommission

This sequence moves Teams chat history and daily conversation into Mattermost in controlled stages, so each stage has a documented output before the next begins. It ends with Teams chat switched off and the retained evidence filed, not with an unverified assumption that the import was complete.

Inventory teams, channels and retention needs
Start by listing every team, channel, private channel and chat that holds content you need, with its owner, member count and the retention rule that applies to it. Ask legal, compliance and records staff which content must be kept and for how long, and confirm which Teams licenses are assigned to the accounts you plan to export, since the Teams Export APIs require an active Teams license on each exported user. The output is an inventory register that maps every source conversation to a target Mattermost channel, an owner and a retention decision. The step is done when the register has been signed off by the business owners and the compliance lead.
Confirm export permissions and Graph access
Your Microsoft 365 administrator registers the application that will call the Teams Export APIs in Microsoft Graph and grants the admin-approved application permissions it needs. Test the access with a single account before relying on it, and record which message types the export returns, such as channel, group, meeting and one-to-one messages, along with any meeting recording or transcript links. The output is a short access record covering the app registration, the granted permissions, the test account and the list of content types you can and cannot retrieve. The step is done when a test call returns the expected messages for a known conversation.
Run a pilot team export and import
Choose one team with a small, low-risk channel set and export its history through the Graph Teams Export APIs. Convert the export into Mattermost's bulk import format, load it into a staging Mattermost server, and check that channels, users, threads and attachments arrived as expected. Record what did not move, such as any content types outside the export scope, and confirm that message counts and timestamps match the source for a sample of conversations. The output is a validated import report listing counts per channel, unmatched users, skipped items and open defects. The step is done when the business owner accepts the report and every defect has an owner and a fix or an accepted workaround.
Map users and identity before full load
Match each Teams identity to its Mattermost account, using the same email address as the stable key where your directory allows it. Decide how single sign-on will be configured, using SAML or OIDC in the Professional or higher edition if you need it, and confirm the license tier against the features you need, because SSO and AD/LDAP sync are not part of the free Team Edition. The output is a user mapping table and an identity decision record. The step is done when a test account can sign in through the chosen method and every migrated user resolves to one Mattermost account.
Run Mattermost and Teams in parallel
Open the Mattermost server to the pilot group and the migrated teams while Teams stays active for everyone else. Use a written rule for where new messages belong during this period, and have the owners of each team post a notice in both tools. Track adoption, missing messages, notification problems and integration gaps in a shared issue log, and run the full import again for the remaining teams once the pilot defects are closed. The output is a parallel run log and a go or no-go decision for each team. The step is done when the log shows no open high-severity issues for a full working cycle agreed with the business owners.
Cut over with communication and link redirects
Send a dated notice to every user explaining when new conversations move to Mattermost, how to sign in, and where to find history. Replace links to Teams channels in intranet pages, runbooks and wikis with Mattermost links, and set a fixed point after which Teams accepts no new posts for the migrated teams. Document the rollback path before the switch. The output is a signed-off cutover plan with the notice text, the link redirect list and the rollback steps. The step is done when the owners of each migrated team confirm access works and the redirect list covers the most-used links.
Decommission Teams chat and keep evidence
Once cutover is confirmed, remove Teams chat access for migrated users according to your licensing and retention rules, and confirm with your Microsoft 365 administrator which licenses can be reclaimed. Keep the export files, the import reports, the inventory register and the cutover plan in a retention location that meets the policies you set in the first step, and record where each evidence item is stored and who can access it. The output is a decommission record and an evidence index. The step is done when the compliance lead confirms the evidence is retrievable and the Teams content that must be kept has been verified in the archive.

What drives cost and duration in this migration

This table lists the main drivers of cost and effort when moving Teams chat history into Mattermost, who pays for each one, and what to ask for in a written quote. Read it before scoping, because most of the effort sits in the export, mapping and identity work rather than in the Mattermost install itself.

Driver	Why it changes cost or effort	How to keep it down
Volume of channels and messages	Export time, import file count and validation effort grow with channel count and message history. Teams exports are bounded by the scope the admin approves.	Export only the teams and date ranges that must move. Ask the vendor to state how it batches large channels and how it validates imported counts.
Number of exported users and licenses	Graph Teams Export APIs require an active Teams license on each exported user, so license costs can recur for users who are not yet offboarded. The migration team pays for extra license months.	Schedule exports before license removal. Confirm with your Microsoft account team which accounts must stay licensed during the export window.
Integrations and bots to rebuild	Teams connectors, bots and Power Automate flows do not carry over. Each one needs a Mattermost replacement, webhook or integration, which is paid build effort.	Inventory integrations first and retire unused ones. Ask for a line-item estimate per integration in the quote.
SSO and identity mapping	Mapping Entra ID users to Mattermost accounts, matching emails and handling duplicates needs an identity design. SSO through SAML or OIDC is included from the Professional plan (Mattermost pricing page).	Decide the identity source before import. Ask the implementer whether AD/LDAP sync or SAML will be configured and who owns the identity provider.
File storage and high availability	A Mattermost high availability cluster requires shared file storage on Amazon S3, an S3-compatible service or NAS mounted on each node. Local file system storage will not work correctly and risks corrupting files (Mattermost high availability docs). Teams files and attachments are a separate volume to plan.	Size storage for migrated attachments before cutover. Ask whether the quote covers shared storage setup, backup and failover testing.
Compliance and retention requirements	Legal hold, retention rules and audit exports change the scope of mapping and testing. Compliance export is part of paid Enterprise tiers (Mattermost editions documentation).	Confirm retention obligations with legal before import. Ask whether the quote includes evidence for assessors, which DeployOpen prepares but auditors do not issue.
Mattermost edition chosen	Team Edition is free, but aimed at teams under 250 users without single sign-on. Professional, Enterprise and Enterprise Advanced are prepaid annual subscriptions based on seat licenses, and their list prices are not published (Mattermost pricing page).	Match the edition to the required features before scoping. Ask the vendor for a written seat-based quote and for what changes if the user count grows.

What usually goes wrong and how to prevent it

Most failed Teams-to-Mattermost migrations trace back to a few predictable gaps: export permissions, license timing, content that never leaves the source, and a cluster or edition set up without the components it needs. Each card below names one of these failure points and the check that prevents it before cutover.

Export permissions not approved

The Teams Export APIs in Microsoft Graph rely on admin-approved application permissions. If the tenant administrator has not granted them, the export calls fail or return partial content, and the gap often appears only after users have stopped writing to Teams. Confirm the granted permissions in the tenant before the export window opens, and run a test export on one team and one private chat to verify the output.

Exports after licenses lapse

The Export APIs require an active Teams license on each user whose content is being exported. Removing licenses at a renewal or during offboarding can cut off history for users who left early, so their chats are lost even though the data still exists. Export while licenses are still active, and keep a written list of which users were covered by each export run.

Integrations and custom emoji left behind

Mattermost's Slack converter moves users, channels, direct messages, threads and attachments, but integrations, custom emoji images and user groups do not transfer. Teams bots, connectors and custom emoji used in messages will appear as plain text or broken references after import. Inventory the apps and emoji in use before migration, then decide which integrations to rebuild as Mattermost webhooks or bots and which emoji to re-upload by hand.

Unsupported content silently dropped

Content that falls outside the importer's supported set can disappear without an error. Tabs, embedded apps, Planner boards, meeting recordings and transcripts that the Export APIs return as links are not chat messages, so they need a separate plan. Map each content type to a destination such as a file share or archive, and reconcile message counts per channel after the bulk import.

File storage misconfigured on clusters

A high availability Mattermost cluster needs shared file storage on Amazon S3, an S3-compatible service or NAS mounted on every node. Local file system storage does not work correctly in a cluster and risks corrupting files, which surfaces as broken attachments after the imported history is loaded. Test attachment upload and download from every application node before loading production data, and confirm that clustering is available on the edition you chose.

Team Edition limits versus SSO needs

Mattermost Team Edition is free and aimed at teams under 250 users that do not need single sign-on. If the Teams estate relied on Entra ID sign-in and directory-driven user management, moving to Team Edition removes SAML, OIDC and AD/LDAP sync, and the Entry tier also caps channel history at 10,000 messages. Decide before the import whether SSO and directory sync are required, because paid plans change the edition and licensing you must budget for.

User confusion at cutover

Users who expect Teams channels, meeting links and familiar notifications will look for them in Mattermost on day one. Without a clear cutover date, a read-only period for Teams, and a list of where each team's channels were rebuilt, people keep posting in both places and history splits. Publish a single cutover date, freeze Teams writes for the migrated scope, and give each team a short guide that maps old channels to new ones.

How the migration differs by organization size and starting point

Small teams that do not need single sign-on can start with Mattermost Team Edition, which Mattermost describes as free, open source, self-hosted and aimed at teams under 250 users. The migration work is mostly technical: export Teams history, convert it, load it, and give people local or invited accounts. There is no license purchase to negotiate, so the recurring costs are the server, database, storage, backups and the time of whoever operates the platform. Confirm the edition terms directly with Mattermost before you build on them.

Account setup: Users sign in with accounts created on the server rather than through a corporate identity provider, so plan how onboarding and offboarding will be handled by hand.
Retention: Confirm whether the free edition's history limits in the Entry tier apply to your deployment, since that tier caps channel history at 10,000 messages.
Staffing: One or two people will own upgrades, which Mattermost publishes monthly, so budget their time rather than treating the server as hands-off.
Backups: Test restores of the PostgreSQL database and the file store together, because a chat history is only useful if messages and attachments come back in step.
Growth path: Ask Mattermost what changes if headcount passes the team size the free edition targets.

Before committing, confirm which features your team actually needs from the edition you pick.

Questions buyers ask before migrating from Teams to Mattermost

How much effort and cost should we expect for a Teams to Mattermost migration?

Expect cost to come from people and infrastructure rather than from a software fee for the Mattermost Team Edition, which is free and open source. The main cost components are the hours for export scripting and import, the Mattermost server and PostgreSQL hosting, shared file storage if you run a high availability cluster, and the staff who run the platform afterward. Costs recur for hosting and operations, and the one-time part is the migration itself. The amount of history, the number of users and whether you need paid features such as SSO drive the total. The Teams Export APIs also require Teams licenses on exported users, so keep those in the estimate. Ask any integrator for a fixed-scope quote that lists each component separately, and ask Mattermost for current pricing from its pricing page, which lists no public prices.

How long does a Teams to Mattermost migration take?

Timeline depends on the volume of chat history, the number of teams and channels, how many users need access, and how quickly your admins approve the Graph permissions. Export and import are the parts most sensitive to volume, and the Teams Export APIs run against each user or conversation, so large tenants take longer to extract. Plan separate phases for permission approval, a pilot export, a test import into a non-production Mattermost server, user mapping and cutover. We do not have a supplied duration for this work, so ask any provider to state its estimate in a written scope and confirm the phases against your own tenant size.

What does the migration need from our Microsoft 365 admins and identity team?

The migration needs a Microsoft Entra ID admin to approve the application permissions that the Teams Export APIs use in Microsoft Graph, and every exported user must hold an active Teams license while the export runs. Your identity team must decide how Mattermost users map to Entra ID accounts, whether email addresses will match, and how sign-on will work after cutover. Single sign-on through SAML or OIDC is documented for Mattermost, but the SSO features are part of paid plans, so the identity design depends on which edition you buy. Confirm the exact permission names and consent steps with Microsoft's Teams export documentation before the project starts, because your tenant policies may require extra review.

Can our internal IT team run the migration without outside help?

An internal team can run the migration if it has someone comfortable with Microsoft Graph authentication, scripting exports, PostgreSQL and Linux server administration, and the Mattermost bulk import tooling. The Mattermost migration path for Slack uses the mmetl converter and mmctl, while Teams content must be converted into the bulk import format by your own script, so developer time is the key input. Teams often find the hard parts are permissions approval, data mapping and testing, not the server build. Consider a fixed-scope engagement if your team lacks Graph scripting or if the migration must finish before a Teams license renewal date. Ask any provider what it will deliver, which steps stay with your staff, and who owns the converter code after handover.

Do private chats and meeting recordings move to Mattermost?

The Teams Export APIs can return 1:1 and group chat messages, channel messages, meeting messages and links to meeting recordings and transcripts, so those items are available to export if your admins grant the permissions. Moving them into Mattermost is a separate step. Meeting recordings are video files stored in Microsoft's services, and a chat import does not play them inside Mattermost, so most teams keep recordings as linked files in a storage system they control. Confirm with your admins which conversations are in scope, because private conversations raise consent and policy questions. Check the Mattermost bulk import documentation for each content type before you promise users that history is complete.

How do SSO and paid plan choices affect the migration project?

SSO and directory sync decide much of the project's scope. According to the Mattermost pricing page, SSO through SAML, OIDC or OAuth and AD/LDAP user sync are included from the Professional plan, while high availability clustering and FIPS 140-3 compliance start at Enterprise, and air-gapped deployment is in Enterprise Advanced. Mattermost Team Edition is free and aimed at teams under 250 users that do not need SSO. If you choose a plan with SSO, the identity integration becomes part of the scope, and the plan is sold as prepaid annual seat licenses. A high availability cluster also needs shared file storage on S3, an S3-compatible service or NAS on each node. Decide the edition before scoping the work, and ask Mattermost to confirm current plan contents.

What happens to our Teams data after the migration?

Plan for both the imported history and the retention of the source data. Mattermost stores imported messages in your own database, but it does not automatically delete Teams data, so decide whether the Teams tenant keeps a read-only archive and for how long. Retention rules, legal holds and records policies should be written before export begins. Ask your compliance lead whether exported content needs encryption at rest and controlled access on the export machine, since the export files contain sensitive messages. Note that Mattermost Entry caps channel history at 10,000 messages and lacks compliance export, so review which edition meets your retention needs before importing.

Who should own which parts of the migration

The Microsoft 365 administrators own the source side and should start first, because the export depends on their decisions. They must grant the admin-approved application permissions that the Microsoft Teams Export APIs in Microsoft Graph require, and confirm that every user whose chat will be exported holds an active Teams license, since the API will not return content for unlicensed users. They also own the export window: content that Teams has already deleted may no longer be recoverable, so this team should confirm retention settings and the deletion windows for their tenant before anything else is scheduled. Ask them to document which teams, channels, one-to-one chats and group chats are in scope, because that list becomes the migration's acceptance criteria.

The identity team owns the path from Entra ID to Mattermost single sign-on. They choose the SSO method, configure the SAML or OIDC application, map the claims that populate usernames and email addresses, and decide how existing accounts are matched so that imported history attaches to the right people. Mattermost's SSO and AD/LDAP sync are included from the Professional plan, so this team also needs to confirm the licensing tier before they design group sync. The platform team owns the Mattermost server, the PostgreSQL database, file storage and backups. Imported attachments and the database grow together, so this team should size storage before the import, confirm where backups are taken, and rehearse a restore on a non-production copy.

Data handling decisions stay with the client, not with DeployOpen or any vendor. The organization decides which content is exported, which personal data is retained or excluded, who may read the imported archive, how long it is kept, and whether any legal hold applies. Those decisions should be recorded by a named owner from the data protection or records function before the export starts. DeployOpen can plan, implement and document the controls and evidence, but it does not decide what the organization is permitted to keep, and it does not issue audit reports or certifications. Each team should sign off its part in writing so that gaps between the three sets of responsibilities are visible before cutover.

How DeployOpen scopes, runs and supports the Mattermost migration

DeployOpen plans and implements self-hosted Mattermost inside your own cloud accounts, data centers or air-gapped networks, and treats the Teams export as a defined workstream. Engagements are fixed-scope, with the export, conversion, import and cutover agreed in writing before any work starts.

How we scope

Inventory the Teams tenant, teams, channels, private channels and chat types that must move
Confirm the admin-approved Graph permissions and Teams licenses available for each exported user
Agree in writing which history windows, attachments and integrations are in and out of the migration
Define the target Mattermost edition, hosting model and single sign-on requirements before build

How we build

Deploy Mattermost in your environment with PostgreSQL and shared file storage sized to the chosen plan
Run the Teams Export API extraction under your admin approval, keeping exported data inside your boundary
Convert exported messages into Mattermost's bulk import format and load them in a staging instance first
Test imported channels, threads, attachments and user mappings against an agreed checklist before cutover

How we hand over

Deliver architecture, configuration and import runbooks written for your own platform team
Document what did not migrate, such as meeting recordings, integrations and custom emoji, with owners for each gap
Provide evidence of the import run and test results that your auditors or compliance team can review
Train administrators on user, channel and retention management in your Mattermost instance

How we support

Offer ongoing support, upgrades and continuous testing as a retainer after cutover
Plan Mattermost version upgrades against the published server release and support schedule
Keep backup and restore procedures tested for the Mattermost database and file storage
Confirm with us in the written scope which support hours and response terms apply