Jak ve Flutteru udělat kontaktní formulář, který odesílá e-maily

Do aplikace ve Flutteru přidáte kontaktní obrazovku, která každou zprávu pošle do vaší schránky. Aplikace obsahuje jen veřejný klíč; e-mail odešle Frontmail přes vaši vlastní schránku, takže v balíčku aplikace neskončí žádné SMTP heslo ani server.

Budete potřebovat: bezplatný účet Frontmail, projekt ve Flutteru 3.24+ a zhruba patnáct minut.

1. Připojte schránku a vytvořte šablonu

1. E-mailové služby → Přidat službu: připojte Gmail, Outlook, SMTP nebo transakční službu, zaškrtněte Nastavit jako výchozí a klikněte na Ověřit a uložit.
2. Šablony → Z galerie → Kontaktní formulář → Použít šablonu. Šablona očekává name, email a message (povinné) a phone, topic (nepovinné).
3. Na záložce Kód pro web zkopírujte ID šablony (tpl_…).

2. Povolte mobilní aplikace

Aplikace na rozdíl od webů neposílají hlavičku Origin, a proto je API odmítá, dokud to nepovolíte: Zabezpečení → Mobilní aplikace → zapněte Povolit mobilní aplikace → Uložit.

Pak v šabloně otevřete Nastavení → Ochrana a zapněte Vyžadovat CAPTCHA (Turnstile). Mobilní aplikace používají sdílený widget Turnstile od Frontmailu, takže žádné vlastní klíče od Cloudflaru nepotřebujete.

3. Nainstalujte balíček

flutter pub add frontmail webview_flutter url_launcher

webview_flutter zobrazuje kontrolu Turnstile. Na Androidu potřebují release buildy navíc <uses-permission android:name="android.permission.INTERNET"/> v AndroidManifest.xml.

Z části o Turnstile v dokumentaci Flutter SDK si zkopírujte widget TurnstileView do lib/turnstile_view.dart – je to zhruba šedesát řádků, které patří vám a můžete si je upravit.

4. Postavte formulář

import 'package:flutter/material.dart';
import 'package:frontmail/frontmail.dart';

import 'turnstile_view.dart';

final frontmail = Frontmail(publicKey: 'pk_…'); // create once, share

class ContactScreen extends StatefulWidget {
  const ContactScreen({super.key});

  @override
  State<ContactScreen> createState() => _ContactScreenState();
}

class _ContactScreenState extends State<ContactScreen> {
  final _name = TextEditingController();
  final _email = TextEditingController();
  final _message = TextEditingController();
  TurnstileSite? _site;
  String? _token;
  int _resetId = 0;
  bool _sending = false;
  String _info = '';

  @override
  void initState() {
    super.initState();
    Turnstile.site(client: frontmail).then((site) => setState(() => _site = site));
  }

  Future<void> _send() async {
    final site = _site, token = _token;
    if (site == null || token == null) return;
    setState(() {
      _sending = true;
      _token = null; // a token works only once
      _resetId++;
    });
    try {
      await frontmail.send(
        templateId: 'tpl_…',
        params: {'name': _name.text, 'email': _email.text, 'message': _message.text},
        options: SendOptions(turnstileToken: token, turnstileKey: site.turnstileKey),
      );
      setState(() => _info = 'Thank you! We’ll get back to you soon.');
    } on FrontmailException catch (e) {
      setState(() => _info = e.message);
    } finally {
      setState(() => _sending = false);
    }
  }

  @override
  Widget build(BuildContext context) {
    final site = _site;
    return Scaffold(
      appBar: AppBar(title: const Text('Contact us')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          TextField(controller: _name, decoration: const InputDecoration(labelText: 'Name')),
          TextField(controller: _email, decoration: const InputDecoration(labelText: 'Email'), keyboardType: TextInputType.emailAddress),
          TextField(controller: _message, decoration: const InputDecoration(labelText: 'Message'), maxLines: 5),
          const SizedBox(height: 16),
          if (site != null)
            TurnstileView(
              site: site,
              resetId: _resetId,
              onMessage: (m) => setState(() => _token = m is TurnstileToken ? m.token : null),
            ),
          FilledButton(onPressed: _token == null || _sending ? null : _send, child: const Text('Send')),
          Text(_info),
        ],
      ),
    );
  }
}

SDK samo opakuje pokusy při chybách sítě a výpadcích serveru s jedním idempotency key, takže nestabilní mobilní připojení nikdy nevytvoří duplicitní e-maily.

5. Vyzkoušejte to

Spusťte aplikaci, vyplňte formulář a klepněte na Send. E-mail dorazí do vaší schránky a objeví se v sekci Historie v dashboardu.

• origin_not_allowed – volba Povolit mobilní aplikace je vypnutá (nebo neuložená).
• captcha_required – chybí token Turnstile; počkejte, až kontrola doběhne.
• invalid_template_params – povinné pole je prázdné nebo e-mailová adresa není platná.

Když dojdou kredity, zpráva se přijme se stavem held a odešle se automaticky po dobití – podle result.status == DeliveryStatus.held to můžete dát uživateli vědět.

Další kroky

• Pošlete uživateli potvrzení pomocí šablony Automatická odpověď: díky za zprávu z galerie.
• Předejte SendOptions(locale: …), aby e-mail odešel v jazyce uživatele, pokud má šablona jazykové verze.