Firebase自定义邮件验证模板技术咨询：Flutter新手的实现疑问及完整示例需求

算力阿峰

2026-4-30

Customizing Firebase Email Verification Templates for Flutter

Hey there! Let's break down your questions one by one and walk through a practical example to help you add images and polish the UI of your Firebase email verification templates.

Your Questions Answered

1. Where should I implement the 'custom email action handler'?

The custom email action handler is a web-accessible page (could be a Flutter Web route, a static HTML page hosted on Firebase Hosting, or any other publicly accessible URL) that handles user clicks on the verification link in your email.

Firebase will redirect users to this URL with a special oobCode (one-time code) as a query parameter. Your handler's job is to take this code, call Firebase Auth's applyActionCode method to complete verification, then redirect the user to your app or show a success message.

You configure this URL in the Firebase Console: Go to Authentication > Templates > Custom Action URL and paste your handler's URL.

2. Do I need the Firebase Admin SDK?

You don't need it for basic template customization (like adding images or editing HTML). But if you want to:

Generate fully custom verification links (with extra parameters like user IDs)
Send completely customized emails (beyond what the Firebase Console template editor allows)
Trigger email verification programmatically after user creation
Then yes, you'll need the Admin SDK (usually used in Cloud Functions or your backend).

3. Do I need an SMTP server to send emails?

Nope! Firebase Auth handles sending verification emails out of the box. But if you want full control over the email delivery process (like using your own domain for sending, or integrating with a third-party email service like SendGrid), you can set up an SMTP server or use an email API with the Admin SDK. For most cases, Firebase's default email service is sufficient.

4. Should the email template be implemented in the Flutter app or Firebase platform?

The email template itself (HTML, images, text content) is configured in Firebase—either via the Firebase Console template editor or generated dynamically using the Admin SDK.

Your Flutter app only handles the post-click logic: when a user opens the verification link, your app (or web handler) processes the verification code and updates the user's status. You don't build the email template inside your Flutter code.

Full Example Workflow

Let's walk through a complete setup to add a custom logo and polished UI to your verification emails, plus a Flutter Web handler.

Step 1: Host Your Custom Image

Upload your logo or images to Firebase Storage, make sure they're publicly accessible (set storage rules to allow read access), and copy the public URL (e.g., https://firebasestorage.googleapis.com/v0/b/your-project-id.appspot.com/o/logo.png?alt=media).

Step 2: Customize the Email Template in Firebase Console

Go to Authentication > Templates and select the "Email verification" template.
Switch to the HTML tab.
Edit the template to add your image and style it. For example:

<!DOCTYPE html>
<html>
  <body style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px;">
    <div style="text-align: center;">
      <img src="YOUR_IMAGE_URL_HERE" alt="App Logo" style="width: 120px; margin-bottom: 20px;">
      <h1 style="color: #2d3748;">Verify Your Email Address</h1>
    </div>
    <p>Hi {{user.displayName}},</p>
    <p>Thanks for signing up! Click the button below to verify your email address:</p>
    <div style="text-align: center; margin: 30px 0;">
      <a href="{{action_url}}" style="background-color: #2b6cb0; color: white; padding: 12px 24px; border-radius: 4px; text-decoration: none;">Verify Email</a>
    </div>
    <p>If the button doesn't work, copy and paste this link into your browser:</p>
    <p>{{action_url}}</p>
    <p>Thanks,<br>The YourApp Team</p>
  </body>
</html>

Save the template—Firebase will use this for all future verification emails.

Step 3: Build a Flutter Web Verification Handler

If you want users to land in your Flutter app after clicking the link, set up a Flutter Web route to handle verification:

Add the firebase_auth package to your pubspec.yaml.
Create a verification page:

import 'package:firebase_auth/firebase_auth.dart';
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart'; // Or use your preferred routing package

class EmailVerificationPage extends StatelessWidget {
  final String? oobCode;

  const EmailVerificationPage({super.key, required this.oobCode});

  Future<void> _verifyEmail(BuildContext context) async {
    if (oobCode == null) {
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Invalid verification link')),
      );
      return;
    }

    try {
      await FirebaseAuth.instance.applyActionCode(oobCode!);
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Email verified successfully!')),
      );
      // Redirect to your app's home page
      context.go('/home');
    } catch (e) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('Verification failed: ${e.toString()}')),
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Verify Email')),
      body: Padding(
        padding: const EdgeInsets.all(20.0),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Text('Click the button below to verify your email'),
            const SizedBox(height: 20),
            ElevatedButton(
              onPressed: () => _verifyEmail(context),
              child: const Text('Verify Email'),
            ),
          ],
        ),
      ),
    );
  }
}

Configure your router to extract the oobCode query parameter and navigate to this page:

final GoRouter _router = GoRouter(
  routes: <RouteBase>[
    GoRoute(
      path: '/verify-email',
      builder: (BuildContext context, GoRouterState state) {
        final oobCode = state.queryParams['oobCode'];
        return EmailVerificationPage(oobCode: oobCode);
      },
    ),
    // Other routes...
  ],
);

Deploy your Flutter Web app to Firebase Hosting (or another hosting service) and copy the URL (e.g., https://your-app.web.app/verify-email).

Step 4: Set the Custom Action URL in Firebase Console

Go to Authentication > Settings > Templates > Custom Action URL and paste your Flutter Web verification page URL. Now, Firebase will send users to this page when they click the verification link.

Bonus: Using Admin SDK for Fully Custom Emails

If you want even more control (like sending emails with dynamic user data), use a Cloud Function with the Admin SDK:

const functions = require("firebase-functions");
const admin = require("firebase-admin");
admin.initializeApp();

exports.sendCustomVerificationEmail = functions.auth.user().onCreate(async (user) => {
  // Generate a custom verification link
  const actionCodeSettings = {
    url: `https://your-app.web.app/verify-email?userId=${user.uid}`,
    handleCodeInApp: true,
  };

  const verificationLink = await admin.auth().generateEmailVerificationLink(
    user.email,
    actionCodeSettings
  );

  // Send a fully custom email (you can use nodemailer here for SMTP)
  await admin.auth().sendEmailVerification(user, {
    url: verificationLink,
    subject: "Welcome to YourApp! Verify Your Email",
    html: `
      <html>
        <body style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px;">
          <div style="text-align: center;">
            <img src="YOUR_IMAGE_URL_HERE" alt="YourApp Logo" style="width: 120px; margin-bottom: 20px;">
            <h1 style="color: #2d3748;">Welcome, ${user.displayName || 'Friend'}!</h1>
          </div>
          <p>Thanks for joining us. Click the button below to verify your email and start using YourApp:</p>
          <div style="text-align: center; margin: 30px 0;">
            <a href="${verificationLink}" style="background-color: #2b6cb0; color: white; padding: 12px 24px; border-radius: 4px; text-decoration: none;">Verify Email</a>
          </div>
          <p>If the button doesn't work, copy and paste this link into your browser:</p>
          <p>${verificationLink}</p>
          <p>Cheers,<br>The YourApp Team</p>
        </body>
      </html>
    `,
  });
});

Deploy this function, and it will automatically send your custom verification email whenever a new user signs up.

内容的提问来源于stack exchange，提问作者user16754196