# Migration

Use these notes when upgrading projects to the 1.0.0 release of the Email module or adopting new
transports.

## From Scaffolded Prototype (\< 1.0.0) to 1.0.0

- Regenerate the module to pick up the new runtime, FastAPI loader, and NestJS service.
- Replace any direct imports of `rapidkit.modules.email` with
  `rapidkit.runtime.communication.email`.
- Update configuration keys:
  - `from_address` → `from_email`
  - `templates.directory` → `template.directory`
  - Remove any custom `status()` helpers; use the built-in status or health functions.
- Review environment files to align with the new `RAPIDKIT_EMAIL_*` variables generated by the
  snippet.

## Migrating SMTP Credentials

- Rotate credentials when enabling TLS or switching ports.
- Validate connections by running `await service.verify_connection()` in staging before production
  rollout.
- Store secrets in RapidKit Vault or your cloud secret manager instead of plaintext `.env` files.

## Adopting Console Mode for Local Development

- Set `RAPIDKIT_EMAIL_PROVIDER=console` and `RAPIDKIT_EMAIL_DRY_RUN=true` to log payloads without
  transmitting them.
- Use this mode when migrating to new template sets so that QA can verify rendered content safely.

## Introducing Custom Providers

- Implement a custom transport and migrate endpoints incrementally using a feature flag.
- Keep SMTP enabled as a fallback until the new provider passes observability and deliverability
  checks.
- Document any provider-specific headers inside your overrides module so downstream consumers can
  update quickly.
