E-Mail-Versand (eigener SMTP)

Tenant-eigener Mail-Transport plus Admin-Benachrichtigungen via sendAdminEmail.

Tools, die E-Mails versenden — Lead-Bestätigungen, Admin-Reports, Newsletter-Triggers — laufen standardmäßig über den Plattform-SMTP. Sobald Mails mit deiner eigenen Absenderadresse rausgehen sollen (nicht über den Plattform-Mailer), konfiguriert ihr ein eigenes SMTP-Profil pro Workspace.

#Eigener SMTP-Transport

In email.php deines Workspace:

return [
    // ... email.prompt, email.tools etc.

    'email.senders' => [
        'default' => [
            'from'     => ['noreply@firma.de' => 'Firma GmbH'],
            'reply_to' => 'kontakt@firma.de',
            'transport' => [
                'host'     => 'smtp.example.com',
                'port'     => 587,
                'username' => '...',
                'password' => '{{secret:MAIL_PW_DEFAULT}}',
                'tls'      => true,
                'timeout'  => 30,   // optional
            ],
        ],
    ],
];

Der default-Eintrag ist Pflicht, damit der Tenant-eigene Mailer überhaupt aktiv wird. Ohne email.senders läuft alles über den globalen Plattform-Mailer.

#Passwort als {{secret:KEY}}-Marker (empfohlen)

transport.password (und transport.username) unterstützen denselben {{secret:KEY}}-Marker wie IMAP-Mailboxen und API-Tools: der Marker wird gegen die untracked .env des Tenants aufgelöst (shared/tenants_untracked/<code>/.env auf Prod, tenants_untracked/<code>/.env lokal), nie im Repo oder im LLM-Kontext aufgelöst. Fehlt der Key in der .env, bricht der Mailer-Aufbau mit einer klaren Exception ab — es wird nie mit leerem Passwort gesendet.

Mehrere Postfächer desselben Workspace (z.B. ein SMTP-Profil pro Mailbox) bekommen je einen eigenen .env-Key, z.B. MAIL_PW_SUPPORT, MAIL_PW_INFO.

Klartext-Werte ('password' => '...') funktionieren weiterhin — reine Abwärtskompatibilität für Bestandsfälle wie config/tenants/bloomify/email.php, die (Stand heute) nicht umgestellt sind.

#Ohne eigenes Profil: Workspace-Adresse als Absender

Ohne email.senders (z.B. Postfach-Piloten aus Signup oder bin/setup-pilot.php) gehen Mails — auch Antworten aus der Inbox — über den Plattform-SMTP mit der Workspace-Adresse als Absender: <Workspace-Name> <firma-a1b2c3@meco-media.com>, Reply-To dieselbe Adresse. Antwortet der Empfänger, landet seine Mail wieder in diesem Workspace und über In-Reply-To im selben Thread. Genommen wird die erste zugewiesene Adresse auf der Plattform-Domain; Anzeigename ist name aus der Workspace-Config. Nur ohne zugewiesene Adresse bleibt der Plattform-Absender TaskMonkey <gpt@meco-media.com>. Dasselbe gilt für ein Profil ohne transport, das kein (erlaubtes) from setzt.

Mehrere benannte Profile sind erlaubt — z.B. support, noreply, marketing mit unterschiedlichen Absenderadressen.

#Profil ohne eigenen transport

Fehlt transport, geht die Mail über den Plattform-SMTP. Dann gilt from (und sender) nur, wenn die Adresse deinem Workspace gehört: zugewiesene Workspace-Adresse (z.B. firma-a1b2c3@meco-media.com, vergibt der Betreiber per bin/cake inbound_addresses) oder eine Plattform-Adresse <workspace-code>-…@meco-media.com. Jede andere Adresse wird ersetzt: Absender ist dann der Plattform-Absender, Reply-To deine Workspace-Adresse. Eine eigene Domain als Absender braucht deinen eigenen SMTP (transport).

#Mailer im Tool benutzen

Jedes Tool bekommt im Context einen Mailer-Builder:

'handler' => function (array $results, array $args, array $ctx): array {
    $mailer = $ctx['mailer']();        // 'default'-Profil
    // oder: $ctx['mailer']('support')  für ein anderes Profil

    $mailer->setTo('kunde@example.com')
        ->setSubject('Anfrage bestätigt')
        ->deliver('Hallo, wir haben deine Nachricht erhalten.');

    return ['success' => true];
},

Der Mailer ist ein normaler CakePHP-Cake\Mailer\Mailer. From, Reply-To, Sender werden automatisch aus dem Profil gefüllt — du brauchst sie nicht erneut zu setzen.

#Admin-Benachrichtigungen via sendAdminEmail

Für Cron-Reports, Fehler-Notifications und Audit-Trails gibt es das interne Tool sendAdminEmail (in _shared/tools/). Es liefert eine fest formatierte Mail an die Admin-Adressen des Workspace.

#Empfänger-Konfiguration

In deinem Workspace (typisch admin.php oder ein bestehender Config-File):

return [
    'admin_emails' => [
        'info@firma.de',
        'team@firma.de',
    ],
];

sendAdminEmail schickt an diese Adressen, sofern in den Tool-Args nichts anderes steht. Mit recipients-Override kann man pro Aufruf gezielt jemanden anschreiben.

#Aufruf aus einem Domain-Tool

'handler' => function (array $results, array $args, array $ctx): array {
    $report = generateDailyReport();

    $ctx['tool']('sendAdminEmail', [
        'subject' => 'Tagesbericht ' . date('d.m.Y'),
        'lines' => [
            'Verpackt heute: *' . $report['packed'] . '*',
            'Offene Bestellungen: *' . $report['open'] . '*',
            '',
            '---',
            'Top-Artikel:',
            [
                'headers' => ['SKU', 'Anzahl'],
                'rows'    => $report['top_items'],
            ],
        ],
    ]);

    return ['success' => true];
},

#Format des lines-Arrays

Eine Schriftart, eine Größe, eine Farbe — bewusst minimal, damit Inbox-Reports konsistent und schnell scannbar sind.

#Eigenschaften

• internal: true — das LLM kann das Tool nicht selbst aufrufen, nur andere Tools per $ctx['tool']('sendAdminEmail', ...)
• Versand läuft über den Tenant-Mailer (email.senders.default), fällt auf den Plattform-Default zurück wenn nicht konfiguriert
• Wird wie jeder andere Tool-Aufruf in task_executions geloggt — Audit-Trail welche Mail wann an wen ging

#Fallstricke

• Abuse-Schutz: bei selbst gehostetem SMTP einen Reverse-DNS-Eintrag und SPF/DKIM für den from-Domain einrichten, sonst landen Mails im Spam
• Credentials nicht committen — transport.password als {{secret:KEY}}-Marker setzen (siehe oben), Wert in die untracked .env des Tenants, nicht in email.php
• Public-Chats: Mails aus dem Public-Widget heraus sind möglich, aber rate-limit dein Tool, damit niemand das Formular als Spam-Relais missbraucht
• Mehrere email.senders-Profile sind nützlich, wenn dein Workspace verschiedene Marken bedient — z.B. support-Profil mit From=support@…, noreply-Profil mit anderer Adresse für Bestätigungs-Mails

#Verwandt

• Email-Verarbeitung — eingehende Mails ans LLM (email.prompt, email.tools)
• OAuth-Verbindungen — wenn du Google Workspace, Microsoft 365 etc. statt SMTP nutzen willst