ServerpodCloudEmailIdpConfig constructor

ServerpodCloudEmailIdpConfig({
  1. required String appDisplayName,
  2. ServerpodCloudEmailClient? emailClient,
  3. String? runMode,
})

An EmailIdpConfig that works with Serverpod Cloud without configuration.

In development and test run mode, verification codes are logged to the console via Session.alert — the same behavior as the default development setup. In staging and production run mode, emails are sent through the hosted Serverpod Cloud transactional email service (see ServerpodCloudEmailClient).

The staging/production setup reads the scloudAuthEmailKey password, which is provided automatically by Serverpod Cloud. The key is read lazily when an email is sent (not at startup), so a self-hosted server still boots when it is unset. Sending is best-effort: a failure (outage, missing key, non-200, or timeout) is logged and never propagated, so it neither breaks sign-up nor reveals whether an account exists during password reset.

If you want to send emails through a custom provider instead, use EmailIdpConfigFromPasswords.

This requires that a Serverpod instance has already been initialized, as it reads the emailSecretHashPepper password from the passwords.yaml file.

appDisplayName is the name shown to recipients in the emails (at most 64 characters) and is prefilled with the project name in the default template.

The verification codes are generated by the default code generators (8 lower-case alphanumeric characters). They must consist of 1–16 alphanumeric characters (A-Z, a-z, 0-9) to be accepted by the email service.

Implementation

factory ServerpodCloudEmailIdpConfig({
  required final String appDisplayName,

  /// The client used to send emails in staging/production. Defaults to a
  /// [ServerpodCloudEmailClient] targeting the hosted service; override it to
  /// target a different endpoint or for testing.
  final ServerpodCloudEmailClient? emailClient,

  /// The run mode determining whether codes are logged (development/test) or
  /// emailed (staging/production). Defaults to `Serverpod.instance.runMode`;
  /// primarily an override for testing.
  final String? runMode,
}) {
  final resolvedRunMode = runMode ?? Serverpod.instance.runMode;
  final isDevelopment =
      resolvedRunMode == ServerpodRunMode.development ||
      resolvedRunMode == ServerpodRunMode.test;

  // In development/test the codes are logged, so no HTTP client is needed.
  // Otherwise a single client is shared between both senders.
  final client = isDevelopment
      ? null
      : (emailClient ?? ServerpodCloudEmailClient());

  return ServerpodCloudEmailIdpConfig._(
    sendRegistrationVerificationCode: _registrationSender(
      _coreSender(
        appDisplayName: appDisplayName,
        client: client,
        emailType: ServerpodCloudEmailType.signup,
        logLabel: 'Registration',
      ),
    ),
    sendPasswordResetVerificationCode: _passwordResetSender(
      _coreSender(
        appDisplayName: appDisplayName,
        client: client,
        emailType: ServerpodCloudEmailType.lostpassword,
        logLabel: 'Password reset',
      ),
    ),
  );
}