How the VaultMe platform works

This article explains the mechanics of a VaultMe migration: how VaultMe reaches the source and the destination, and what it does with the content it finds there.

How does VaultMe actually migrate content?

VaultMe runs entirely in the cloud. During a migration it holds two conversations at the same time: one with the cloud that hosts the source, and one with the cloud that hosts the destination. Content is read out of the first and written into the second, and that path is the whole of the migration. Nothing runs on an admin's laptop or on an end user's device — there is no agent to install, no browser extension, and no local software in the path the content takes. A browser is needed to set a migration up and to watch it, not to carry content.

This is the mechanism rather than the procedure. For the admin's side of the same migration — creating a project, running the pre-migration scan, paying, and watching the batch — see "How VaultMe works".

Each connection has a single role in a given migration: content is read out of the source and written into the destination. Although the whole workflow is called a migration, what VaultMe performs is a copy. It does not modify, reorganize, or delete anything in the source. Every item stays where it was, in the state it was in, and the source stays usable while the migration runs and after it finishes, until the customer decides to retire it. That has a practical benefit beyond safety: because both sides exist side by side, results can be checked by hand against an unchanged original.

Once a migration has finished, the two sides are independent. A message filed or a file edited in the source afterwards does not appear in the destination on its own; catching up on later changes is a separate, deliberate step. Everything else in this article follows from that path — how fast content can be copied, what VaultMe is able to see, what happens when an individual item cannot be copied, and what "finished" actually means.

How does VaultMe read and write through provider APIs?

Everything VaultMe reads or writes goes through the official, publicly available APIs the providers offer — or, where a provider offers no API, a supported standard protocol such as IMAP. There is no other way in or out, which is why so much of how a migration behaves is really the providers' behavior showing through.

Those interfaces work one item at a time: a message, a file, a calendar event, a contact. A migration is therefore a very large number of small operations rather than one bulk operation, which is why the number of items in a source usually matters more to how long a run takes than the total size of the content does.

Both sides limit how quickly those operations can go through, and the two are not symmetrical. Writing to the destination is usually the slower half, so the destination is often what sets the pace: even when the source hands content over quickly, VaultMe frequently has to wait for the destination to accept it.

To make the most of the capacity that is available, VaultMe works on several things at once wherever the providers allow it:

• Within one migration, the content types run in parallel. Email, files, calendars, and contacts are separate streams, so the time a migration takes is set by whichever stream finishes last rather than by adding the streams up.
• Across a batch, the migrations run in parallel. Migrations in a batch generally run together rather than in a queue, so the largest and most complex ones tend to govern when the batch as a whole finishes.

There is one common exception. When several migrations write into the same destination at the same time, they share whatever API capacity the provider allows there, so VaultMe prefers to run them one after another rather than let them compete.

The limits themselves come from the providers, not from VaultMe. Providers cap how many read and write operations an account can perform within a given window, both to protect their own systems and to stop one customer from crowding out others. Short windows — limits measured per minute — usually just slow a migration down. Longer windows, anywhere from an hour to a full day, can stop it: when one is exhausted, the migration waits for the limit to reset and then picks up where it left off. VaultMe does not hold migrations to a speed cap of its own and cannot negotiate past a provider's limits. What it does instead is keep retrying and keep returning to the fastest speed the provider currently permits.

That behavior is worth recognizing, because a migration that has gone quiet is usually waiting rather than broken. Pausing and restarting it by hand does not win capacity back and can make the total run longer. For what drives duration in practice, and how to read the estimate VaultMe gives you, see "What determines migration duration".

How does VaultMe get access?

Connecting a source or a destination happens on the provider's own sign-in and consent screen. The password is typed into the provider's page, never into VaultMe, and what VaultMe receives back is a token the provider issues for that one connection — permission to act, with a lifetime set by the provider and revocable at any time from the provider's side. That is how it works wherever the provider supports OAuth, the token-based mechanism behind the "Sign in with Google" and "Sign in with Microsoft" flows. Mail systems that offer nothing of the kind, such as plain IMAP servers, may require credentials instead; that is the exception rather than the rule.

VaultMe asks for the smallest set of permissions the migration needs, and what it asks for depends on the role the connection plays: a source connection generally needs permission to read content, while a destination connection generally needs permission to both read and write, since placing content correctly means seeing what is already there. The exact set can also depend on which providers are on either side.

There are two connection methods, and what separates them is who grants access and how much is granted at once:

• Connection using admin authorization. An admin connects an entire environment — a Google Workspace organization or a Microsoft 365 tenant — once, and the user accounts inside it are then connected automatically, without anyone connecting them one by one.
• Connection using resource-level authorization. Each user account is connected on its own, with permissions scoped to that account, by the account holder or by an admin acting on their behalf.

Which method to use on each side, and what each one takes to arrange, is covered in "Choosing a connection method".

User accounts are what gets connected in the great majority of migrations. Shared drives, shared mailboxes, and other kinds of resources can be migrated too; they have to be connected as well.

Both sides have to stay connected for as long as the migration needs them, through the initial run and through any later catch-up pass. Connections are usually broken by something that happens outside VaultMe: a password reset, a revoked token, a change to multi-factor authentication rules, an admin changing environment configuration. When that happens, VaultMe pauses rather than fails. It stops reading and writing, waits, and resumes once the connection is restored.

A connection is the only channel VaultMe has into either side, and there is considerably more to say about what one carries and how far it reaches: see "How VaultMe authentication works".

What does indexing do?

The first thing a migration run does is build an index: a list of every discoverable item in the connected source, limited to the content types you selected for the migration. Nothing is copied until VaultMe knows what there is to copy.

This is not the pre-migration scan. The scan runs much earlier, before any payment: it inspects whether both sides are ready and measures how much content is there so the price and the timeline can be estimated, rather than cataloguing individual items. It is described in the pre-migration scan chapter of "How VaultMe works".

"Discoverable" means what the connected source exposes in the cloud for those content types. That is narrower than what an end user sees on their own computer, where several accounts and clouds are often blended into a single view. VaultMe sees only into the cloud it is connected to, so content that lives anywhere else is invisible to it:

• Mail that is no longer on the server. If a desktop mail client downloaded messages and removed them from the provider's copy, only a local copy remains, and it cannot be indexed. Mail has to be visible in webmail, or in some other server-side view of the mailbox, to be migrated.
• Contacts and calendars kept only on a device. Address books and calendars that live on a handset or in a local app, and never sync to the connected account's cloud contacts or calendars, are not part of the source.
• Files sitting in another cloud. When someone reaches several drives from the same computer, files left in the wrong one — a personal drive rather than the connected organization account, or the other way round — are not in the source until they are placed there.

The finished index is the work list VaultMe then walks. It generally prefers the most recently created or modified items first, but the exact processing order is not guaranteed, so the sequence in which content appears at the destination is not something to read into.

The index also closes at a point in time, and that point is what the initial migration copies. Items added to the source afterwards are not part of that pass; they are picked up later, as described in "How are later source changes copied?". People go on using the source while a migration runs, and that is expected rather than a problem.

Finally, the index outlives the indexing step. As each item is copied, VaultMe records which destination copy it created for that source item, so the index becomes a map between the two sides rather than just a listing of the source. That pairing is what makes any later pass possible.

What happens to each indexed item?

Every item in the index is attempted. The target is item-level coverage of the source: not a destination that looks broadly right, but an accounted-for outcome for each individual message, file, event, and contact.

For each of them, VaultMe aims at the most precise copy the destination can technically hold, preserving structure, formatting, and metadata as far as the destination allows. Each item ends in one of three states:

1. Copied as it stands. The destination accepts the item and its details, and the copy matches the original as closely as the two systems allow.
2. Copied with a transformation or a limitation. The destination cannot take the item exactly as it is, so VaultMe writes the best available representation rather than dropping it. Naming is the everyday case: destinations enforce their own rules about which characters are allowed and how long names and paths can be, so a name may be adjusted or a long path shortened instead of the item being skipped.
3. Skipped. A few items cannot be copied at all — a provider restriction, a missing permission, or another blocking constraint stands in the way. The item is left behind and the reason is recorded.

Trouble along the way is treated as an item-level event, not a run-level one. When a failure is one VaultMe recognizes as a dead end, the item is marked skipped straight away and the run carries on. When the cause is unknown or looks temporary, the item is retried several times in quick succession. If it still does not go through, it is set aside for a manual review by VaultMe staff — a path that applies to only a tiny fraction of items. Who can reach customer data, and when people at VaultMe are involved at all, is covered in "Privacy and security" and "How VaultMe protects migration data". Either way, one problematic item does not hold up the others; the migration pauses only if nothing else is left to process.

One thing VaultMe deliberately does not do is inspect the destination for content that may already be there. It makes no difference whether an earlier VaultMe migration or some other tool put it there, or whether that earlier attempt ran to completion: VaultMe writes its own fresh copy of every in-scope source item, and matches items only against the index it built for the current migration. Running a second migration into a destination that already holds a copy therefore produces a second, independent copy rather than merging with or resuming the first. If an earlier migration has to be redone, the content it wrote should be deleted first.

Through all of this the source is never edited. On the destination side, the result can differ from the source in small ways — an adjusted name here, a skipped item there — and the migration report is the record of exactly that: every discovered item, where it ended up, and a note explaining anything that was transformed or skipped.

How are later source changes copied?

The initial run copies the source as it stood when the index closed, so the destination is complete as of a moment that has already passed by the time the run finishes. Anything that arrived or changed in the source in the meantime — on a large project, that can be a week or more of mail — is not there yet.

A sync-up migration (delta migration) closes that gap. It is a follow-up pass over the same source and destination that copies only what is new or changed in the source since the previous run, matching everything else through the index the initial migration built. One pass runs automatically after every initial migration, catching the changes that landed while the migration was in progress, and further passes can follow, each starting where the one before it ended. Because the pairing is already recorded, unchanged items are not copied again and the destination does not fill up with duplicates.

The design is easier to hold onto once it is clear what a sync-up migration is not:

• It is not continuous synchronization. Each pass is a discrete run over the changes since the last one, not a live mirror that follows the source as it changes.
• It is not a backup of the source. Its purpose is to bring the destination up to date, not to keep a recoverable history of what the source used to contain.
• It is not a reconciliation of the two sides. Only source-side changes flow. An item deleted in the source keeps its copy in the destination, and when a source item changes, the update is written over its destination copy — overwriting any edits someone made there in the meantime.

That makes sync-up migration a bridge rather than an ongoing arrangement. It exists so that a project does not have to squeeze the initial migration and the cutover — the point at which people stop relying on the source and start relying on the destination — into the same narrow window. Content can be migrated well in advance, kept up to date pass by pass, and the switch made when the customer is ready. How to plan that switch is covered in "Planning the cutover and domain switch". It is not meant to run indefinitely, and the ability to keep catching up has a limited life once the passes stop.

How long that window lasts, what a pass copies and leaves alone in detail, and what limits apply are covered in "How sync-up migration works".