Email migration
The email migration switches a provider from SMS-based to email-based user verification. Once it is complete, users verify their identity with a confirmed email address instead of a phone number. It is run as a guided, staged workflow from the provider’s Email migration dashboard in Control Center.
Before each step runs, the provider admin sees a disclaimer on the approval screen that describes exactly what that step will change and which users it affects.
The migration runs in two separate types, each requiring its own approval:
| Type | What it does |
|---|---|
| Sign-up migration | The first step. New registrations are restricted to email, and existing phone-only users are prompted to add and verify an email address the next time they sign in. Sign-in via phone number keeps working, and no accounts are removed. |
| Sign-in migration | The second step. Email becomes the only way to sign in. Active users without a verified email address are archived and locked, and duplicate verified email addresses are cleaned up so that each address identifies a single user. Both actions are irreversible. |
The sign-in migration can only be created after the sign-up migration for the same provider has succeeded.
This workflow reconfigures the provider’s user-email-required setting and the verification channels of its user-facing clients. For the separate, cosmetic configuration of the sender name and address used in outgoing emails, see Email sender configuration.
Roles and access
Permissions:
manage_providers
Two roles cooperate on a migration:
- The provider admin accepts the migration. Accepting is the provider’s explicit authorization for ioki to proceed, and it is the only migration action a provider admin performs.
- An ioki admin (Super Admin) creates the migration, schedules it, sends notifications, and runs every subsequent action. The dashboard shows a warning and hides these controls for non–Super Admin users.
Create a migration
Roles: Super Admin
A migration is created by an ioki admin from the Management Area. Open the provider’s action menu (⚙️) and select:
- Create sign-up email migration. Available when the provider has no sign-up migration yet.
- Create sign-in email migration. Available once the sign-up migration has succeeded and no sign-in migration exists yet. The sign-in migration can also be created directly from the completed sign-up migration dashboard using Proceed to Sign-in Migration.
A newly created migration starts in the Awaiting acceptance state.
Open the dashboard
Once a migration exists and has been accepted (or is at least past the awaiting-acceptance state), open it from the provider view in Control Center: ⚙️ > Email migration.
The dashboard is organized into cards:
| Card | Contents |
|---|---|
| Current state | The migration’s current state. For Super Admins, this card also holds the schedule form (see Scheduling). |
| Overview | User counts for the provider: active users, confirmed email, without verified email, duplicate email, without any email, unverified email, with phone number, and with device. |
| Notification history | Per phase: notifications sent, users notified, users notified multiple times, the maximum notifications sent to one user, and the last notification time. |
| Users grouped by user segment | The same email-readiness counts broken down per user segment. |
| Relevant client configuration | The current verification-channel configuration of each user-facing client, so the effect of applying the migration can be verified. |
Acceptance
Permissions:
manage_providers
While a migration is Awaiting acceptance, the dashboard shows an approval link. The ioki admin shares this link with the provider admin.
On the approval screen the provider admin sees the migration type and a disclaimer describing exactly what the step will do, then selects Accept Migration. Acceptance records who accepted and when, and moves the migration to the Accepted state. Nothing irreversible happens on acceptance itself—it authorizes the ioki admin to begin executing the agreed steps.
Scheduling
Roles: Super Admin
After acceptance, the ioki admin sets the planned timing in the Current state card. The planned datetime is used in the “planned” notifications so users know when the change is coming.
- Planned at. Applies to both migration types.
- Planned duplicate cleanup at and Planned soft deletion at. Sign-in migrations only.
The timing, the notification messages, and the channels used are all managed by the ioki admin in coordination with the provider admin.
Notifications
Roles: Super Admin
At each step the ioki admin can notify affected users over one or more channels:
| Channel | Delivered to |
|---|---|
| Users with a confirmed email address. | |
| SMS | Users with a phone number. |
| In-app / push | Active users, via the existing push / in-app notification pipeline. |
Users missing the address required for a selected channel are skipped automatically, and the skipped counts are reported. Notifications are localized to each user’s locale (falling back to the provider or default locale).
The buttons available depend on the current step:
- Notify planned …. Announces the upcoming migration and requires a planned datetime to be set.
- Notify … migration. Announces that the migration is taking effect now.
- Warn users before duplicate cleanup / Resend duplicate cleanup warning. Sign-in only; warns users whose email address is shared with another account.
- Warn users about archival / Resend archival warning. Sign-in only; warns users who still have no verified email that their account will be archived. Requires Planned soft deletion at to be set.
Sign-up migration workflow
- Accept—the provider admin accepts the migration.
- Notify planned sign-up migration—optionally announce the upcoming change.
- Start sign-up migration—moves the migration to Initiated.
- Notify sign-up migration—optionally tell users the change is now in effect.
- Apply sign-up migration to clients—enables user email address required on the provider and reconfigures its user-facing clients so that new sign-ups use email while sign-in still accepts SMS. The migration goes to Pending while the change is applied in the background and then to Succeeded.
- Proceed to Sign-in Migration—appears once the sign-up migration has succeeded.
At any point before it succeeds, the migration can be cancelled with Cancel sign-up migration.
Sign-in migration workflow
The sign-in migration removes access for users who never added a verified email, so it has extra cleanup steps. When it is started, it automatically advances to the first step that still has work to do, based on the provider’s current user data.
- Accept—the provider admin accepts the migration.
- Start sign-in migration—advances to the first applicable state:
- Initiated if any active users share a duplicate email address.
- Duplicates cleaned if there are no duplicates but some active users still have no email address.
- Users soft deleted if every active user already has a verified email address.
- Duplicate cleanup (state Initiated)—after a duplicate cleanup warning has been sent, Remove duplicate verified email addresses clears the verified email from every affected account except one, then advances to Duplicates cleaned.
- Archival (state Duplicates cleaned)—after an archival warning has been sent, Archive users without a verified email archives and locks the remaining active users that have no verified email, then advances to Users soft deleted.
- Apply sign-in migration to clients (state Users soft deleted)—reconfigures the clients so email is the only sign-in method. This step refuses to run if any active user still has a duplicate or missing email address. The migration goes to Pending and then to Succeeded.
Cancel sign-in migration is available while the migration is in the Initiated, Duplicates cleaned, or Users soft deleted states.
Removing duplicate verified email addresses and archiving users are both irreversible. Make sure enough time has passed and enough warnings have been sent before running either step.
States
| State | Meaning |
|---|---|
| Awaiting acceptance | Created; waiting for the provider admin to accept. |
| Accepted | The provider admin has authorized the migration. |
| Initiated | Started. For sign-in migrations, duplicate email addresses still need cleanup. |
| Duplicates cleaned | Sign-in only. Duplicate verified email addresses have been removed; users without a verified email still need archival. |
| Users soft deleted | Sign-in only. Users without a verified email have been archived; the migration is ready to apply to clients. |
| Pending | The client and provider configuration is being applied in the background. |
| Succeeded | The migration completed. |
| Failed | A step failed. The reason is shown, and the migration can be retried. |
| Cancelled | The migration was cancelled before completion. |
Retrying a failed migration
Roles: Super Admin
If a step fails, the dashboard shows the failure reason. Retry migration returns the migration to the state it was in before the failure so the step can be attempted again.