Módulo de E-mail

Envio de e-mails transacionais e personalizados via SMTP, com histórico, reenvio e painel no dashboard.

Instalação

O módulo de e-mail (sweflow/module-email) é instalado pelo Marketplace do dashboard. Após a instalação:

Configure o SMTP no .env

env

MAILER_HOST=smtp.gmail.com
MAILER_PORT=587
[email protected]
MAILER_PASSWORD=sua_senha_de_app
MAILER_ENCRYPTION=tls
[email protected]
MAILER_FROM_NAME="Minha API"

Execute as migrations

bash

php vupi migrate

Cria a tabela email_history no banco configurado em Database/connection.php do módulo.

Endpoints

Todos os endpoints exigem autenticação admin_system.

Método	Endpoint	Descrição
POST	`/api/email/custom`	Envia e-mail personalizado e salva no histórico
GET	`/api/email/history`	Lista histórico de e-mails (`?q=busca`)
GET	`/api/email/history/{id}`	Detalhe de um e-mail do histórico
DELETE	`/api/email/history/{id}`	Remove um registro do histórico
POST	`/api/email/history/{id}/resend`	Reenvia um e-mail do histórico

Enviando um e-mail

bash

curl -X POST https://api.vupi.us/api/email/custom \
  -H "Authorization: Bearer SEU_TOKEN_ADMIN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      { "email": "[email protected]", "name": "João Silva" }
    ],
    "subject": "Bem-vindo!",
    "html": "<h1>Olá, João!</h1><p>Sua conta foi criada com sucesso.</p>",
    "logo_url": "https://api.vupi.us/assets/imgs/logo.png"
  }'

Múltiplos destinatários:

json

{
  "recipients": [
    { "email": "[email protected]", "name": "Ana" },
    { "email": "[email protected]", "name": "Bruno" }
  ],
  "subject": "Novidade importante",
  "html": "<p>Temos uma novidade para você!</p>"
}

Histórico de e-mails

Todos os e-mails enviados (com sucesso ou com erro) são salvos na tabela email_history. O dashboard exibe o histórico com busca, reenvio e exclusão.

bash

# Listar histórico
curl https://api.vupi.us/api/email/history \
  -H "Authorization: Bearer SEU_TOKEN_ADMIN"

# Buscar por assunto ou status
curl "https://api.vupi.us/api/email/history?q=bem-vindo" \
  -H "Authorization: Bearer SEU_TOKEN_ADMIN"

# Reenviar e-mail
curl -X POST https://api.vupi.us/api/email/history/abc123/resend \
  -H "Authorization: Bearer SEU_TOKEN_ADMIN"

Usando em seu próprio módulo

Injete EmailSenderInterface no construtor do seu service. O container resolve automaticamente para o EmailService do módulo instalado:

php

<?php

namespace Src\Modules\Pedido\Services;

use Src\Kernel\Contracts\EmailSenderInterface;

class PedidoService
{
    public function __construct(
        private readonly PedidoRepository $repository,
        private readonly ?EmailSenderInterface $email = null  // opcional
    ) {}

    public function criar(array $data): array
    {
        $pedido = $this->repository->create($data);

        // Envia confirmação se o módulo de e-mail estiver instalado
        $this->email?->sendCustom(
            $data['email'],
            'Pedido confirmado',
            "<p>Seu pedido #{$pedido['id']} foi criado!</p>"
        );

        return $pedido;
    }
}

Solução de problemas

Erro	Causa	Solução
500 em `/api/email/history`	Tabela `email_history` não existe	Execute `php vupi migrate`
503 ao enviar	`MAILER_HOST` vazio no .env	Configure as variáveis `MAILER_*`
Classe não encontrada após instalar	OPcache desatualizado	Valide o serviço instalado e execute, neste ambiente, `sudo systemctl reload php8.3-fpm`
Conflito de dependências	Versão do PHPMailer incompatível	Ajuste a constraint no `composer.json` do módulo

Reload automático do PHP-FPM

Ao instalar ou desinstalar módulos, o sistema tenta invalidar o OPcache e sinalizar o processo PHP-FPM. O fallback depende das permissões e do nome do serviço do ambiente. Na instalação atual ele é php8.3-fpm; confirme com systemctl status php8.3-fpm.