Change Email (Request)

POST /api/v1/users/change-email — 🔑 Bearer · Rate limit: 3 req / hour

Initiates an email-change flow. Re-confirms the current password, validates the new email (format + disposable-domain + MX + GDPR tombstone + uniqueness), creates a fresh verification token, and queues a verification email to the new address through the active email provider (admin-managed). The account's User.email does not change here — it only flips after the user clicks the link in the verification email (separate verify endpoint, in the auth module).

Request

Body — ChangeEmailDto

Response

200 OK — ApiResponseOf<EmailChangeMessageDto>

{
  "success": true,
  "data": {
    "message": "Verification email sent to your new address. Please check your inbox."
  }
}

Errors

Side effects

1. Normalize submitted email; lookup User; reject if no passwordHash.
2. Bcrypt-compare password against User.passwordHash.
3. Reject if newEmail === user.email (no-op).
4. Email validator — checks disposable-domain blocklist + MX record presence.
5. Reject if any other user already holds this email.
6. GDPR tombstone check — compute sha256(newEmail); if a row exists with email = "deleted_<hash>@deleted.bio.re" AND status = DELETED, reject. (Prevents reusing emails of accounts that were deleted under GDPR right-to-erasure.)
7. Inside one transaction:
   • UPDATE EmailVerification SET verified=true, usedAt=now() WHERE userId=:userId AND newEmail IS NOT NULL AND verified=false — invalidate any pending change-email tokens.
   • INSERT EmailVerification { userId, token=randomUUID(), newEmail, expiresAt = now() + auth.verification_token_expiry_hours } (default 24h).
   • On Prisma P2002 (concurrent email claim), throw email_taken.
8. Queue verification email — notificationService.send({ eventKey: 'email_verification', userId, variables: { username, verifyUrl } }). This enqueues a BullMQ job consumed by worker-service, which dispatches via the active email provider. Failure is logged, not surfaced.
9. Audit log: [emailChange] Verification sent for user {userId} to <masked email> (last-4 prefix masking via maskEmail()).

Code samples

curl -X POST https://api.bio.re/api/v1/users/change-email \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "newEmail": "[email protected]",
    "password": "current-account-password"
  }'

type ChangeEmailInput = { newEmail: string; password: string };
type ChangeEmailResponse = { message: string };

async function changeEmail(accessToken: string, input: ChangeEmailInput): Promise<ChangeEmailResponse> {
  const res = await fetch('https://api.bio.re/api/v1/users/change-email', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(input),
  });
  const json = await res.json();
  if (!res.ok || !json.success) {
    throw Object.assign(new Error(json?.error?.message ?? 'Change email failed'), {
      code: json?.error?.code,
    });
  }
  return json.data;
}

import { useMutation } from '@tanstack/react-query';

export function useChangeEmail() {
  return useMutation({
    mutationFn: async (input: ChangeEmailInput) => {
      const res = await fetch('/api/v1/users/change-email', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Change email failed'), {
          code: json?.error?.code,
          i18nKey: json?.error?.i18nKey,
        });
      }
      return json.data as ChangeEmailResponse;
    },
  });
}

Try it

curl -X POST "https://loading/api/v1/users/change-email" \  -H "Content-Type: application/json" \  -d '{    "newEmail": "[email protected]",    "password": "stringst"  }'

{
  "success": true,
  "data": {
    "message": "Verification email sent to your new address. Please check your inbox."
  }
}

{
  "success": false,
  "error": {
    "code": "AUTH_UNAUTHORIZED",
    "message": "Invalid credentials",
    "i18nKey": "auth.login.invalid_credentials",
    "i18nVars": {
      "field": "email"
    },
    "details": [
      {
        "message": "email must be an email"
      }
    ],
    "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

{
  "success": false,
  "error": {
    "code": "AUTH_UNAUTHORIZED",
    "message": "Invalid credentials",
    "i18nKey": "auth.login.invalid_credentials",
    "i18nVars": {
      "field": "email"
    },
    "details": [
      {
        "message": "email must be an email"
      }
    ],
    "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

{
  "success": false,
  "error": {
    "code": "AUTH_UNAUTHORIZED",
    "message": "Invalid credentials",
    "i18nKey": "auth.login.invalid_credentials",
    "i18nVars": {
      "field": "email"
    },
    "details": [
      {
        "message": "email must be an email"
      }
    ],
    "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Source