Enviar emails con NewMail

Podemos enviar emails desde FacturaScripts utilizando la clase NewMail. Esta clase facilita el envío de emails con los datos configurados en el menú Administrador → Emails.

use FacturaScripts\Dinamic\Lib\Email\NewMail;

$mail = NewMail::create()
    ->to('pepe@gmail.com', 'Pepe')
    ->subject('Hola Pepe')
    ->body('Hola Pepe, esto es una prueba');

if ($mail->send()) {
    // Email enviado correctamente.
}

📎 Añadir un archivo adjunto

Usaremos el método addAttachment() de la clase NewMail para añadir archivos adjuntos al email:

$mail = NewMail::create()
    ->to('pepe@gmail.com', 'Pepe')
    ->subject('Hola Pepe')
    ->body('Hola Pepe, esto es una prueba')
    ->addAttachment('el-archivo.pdf', 'Nombre del archivo para el cliente.pdf');

if ($mail->send()) {
    // Email enviado correctamente.
}

✉️ Enviar con copia

El campo CC en los emails significa "con copia". Se utiliza para enviar una copia a otras personas además del destinatario principal. Las personas incluidas en CC pueden ver las direcciones de los demás destinatarios.

$mail = NewMail::create()
    ->to('pepe@gmail.com', 'Pepe')
    ->cc('jose@gmail.com', 'Jose')
    ->cc('antonio@gmail.com', 'Antonio')
    ->subject('Hola')
    ->body('Hola, esto es una prueba');

if ($mail->send()) {
    // Email enviado correctamente.
}

👁️‍🗨️ Enviar con copia oculta

El campo BCC significa "con copia oculta". Permite enviar una copia sin mostrar la dirección de esos destinatarios al resto.

$mail = NewMail::create()
    ->to('pepe@gmail.com', 'Pepe')
    ->bcc('jose@gmail.com', 'Jose')
    ->bcc('antonio@gmail.com', 'Antonio')
    ->subject('Hola')
    ->body('Hola, esto es una prueba');

if ($mail->send()) {
    // Email enviado correctamente.
}

📫 Notificaciones

En ocasiones debemos mandar el mismo tipo de email muchas veces. Para estos casos podemos preparar una notificación con el texto precargado, que además podrá modificar el usuario.

📝 Cómo crear una notificación

Para crear una notificación usaremos el modelo EmailNotification:

use FacturaScripts\Dinamic\Model\EmailNotification;

$notificationModel = new EmailNotification();
$notificationModel->name = 'mi-notificacion';
$notificationModel->subject = 'mi-titulo';
$notificationModel->body = 'mi-texto';
$notificationModel->enabled = true;
$notificationModel->save();

Podemos usar cadenas de texto a reemplazar, como {name}, que será sustituida por el nombre del contacto o cliente al que enviemos el email.

📨 Cómo enviar una notificación de email

Para enviar la notificación llamaremos a la clase MailNotifier:

use FacturaScripts\Dinamic\Lib\Email\MailNotifier;

MailNotifier::send('mi-notificacion', $email, $name);

Si hemos incluido otras cadenas de texto a reemplazar, por ejemplo una fecha de vencimiento y un nombre de proyecto, podemos pasar sus valores en el cuarto parámetro:

// Texto: "Hola {name}, la fecha de vencimiento del proyecto
// {project} es {expiration}".
MailNotifier::send('mi-notificacion', $email, $name, [
    'project' => 'Proyecto 123',
    'expiration' => '11-12-2024',
]);

📝 Textos predeterminados para emails

Cuando el usuario envía por email una factura, albarán u otro modelo, FacturaScripts utiliza textos predeterminados. Estos textos son notificaciones como sendmail-AlbaranCliente o sendmail-FacturaCliente.

Puedes conseguir el mismo comportamiento con tus modelos creando una notificación cuyo nombre sea sendmail- seguido del nombre de la clase del modelo.

Shortcodes y bloques de email

NewMail convierte los siguientes shortcodes en bloques nativos:

[blockTitle]...[/blockTitle] → TitleBlock.
[blockText]...[/blockText] → TextBlock.
[blockHtml]...[/blockHtml] → HtmlBlock.
[blockButton label="Reservar" href="https://example.com"] → ButtonBlock.
[blockSpace height="20"] → SpaceBlock.

Puedes consultar más ejemplos en Shortcodes para bloques de email.

Además, los bloques se pueden crear directamente desde PHP y añadir al cuerpo con addMainBlock() o al pie con addFooterBlock().

Ejemplo de BoxBlock desde PHP

use FacturaScripts\Core\Lib\Email\BoxBlock;
use FacturaScripts\Core\Lib\Email\TextBlock;

$box = new BoxBlock(
    [
        new TextBlock('Línea 1 del contenido de la caja.'),
        new TextBlock('Línea 2 del contenido de la caja.'),
    ],
    'block mb-15',
    'border: 1px solid #d1d5db; padding: 12px;'
);

$mail->addMainBlock($box);

Parámetros de BoxBlock:

$blocks: lista de bloques hijos (BaseBlock[]).
$css: clase CSS opcional del contenedor.
$style: valor disponible para extensiones; el render nativo no lo aplica directamente.

Ejemplo de TableBlock desde PHP

use FacturaScripts\Core\Lib\Email\TableBlock;

$table = new TableBlock(
    ['Producto', 'Cantidad', 'Precio'],
    [
        ['Teclado', '2', '29.90 EUR'],
        ['Ratón', '1', '19.90 EUR'],
    ],
    'table mb-15 w-100',
    'font-size: 13px;'
);

$mail->addMainBlock($table);

Parámetros de TableBlock:

$header: cabeceras de la tabla.
$rows: filas de la tabla (array<array<string>>).
$css: clase CSS opcional de la tabla.
$style: valor disponible para extensiones; el render nativo no lo aplica directamente.

Crear un shortcode personalizado

Para añadir un shortcode propio hay que crear una clase de bloque dentro de Lib/Email del plugin. La clase debe heredar de BaseBlock e implementar fromShortcode() para transformar los atributos y el contenido del shortcode en una instancia.

Por ejemplo, en Plugins/MiPlugin/Lib/Email/AlertBlock.php:

namespace FacturaScripts\Plugins\MiPlugin\Lib\Email;

use FacturaScripts\Core\Lib\Email\BaseBlock;

class AlertBlock extends BaseBlock
{
    private string $text;

    public function __construct(string $text, string $css = '', string $style = '')
    {
        $this->text = $text;
        $this->css = $css;
        $this->style = $style;
    }

    public static function fromShortcode(array $attrs, string $content): static
    {
        return new static(
            $content,
            $attrs['css'] ?? '',
            $attrs['style'] ?? ''
        );
    }

    public function render(bool $footer = false): string
    {
        $css = empty($this->css) ? 'alert' : $this->css;

        return '<div class="' . $css . '" style="' . $this->style . '">'
            . $this->text
            . '</div>';
    }
}

Registraremos la clase usando su nombre, sin pasar un callable:

use FacturaScripts\Dinamic\Lib\Email\NewMail;

NewMail::addBlockHandler('AlertBlock');

Una vez desplegado el plugin podremos utilizar el nuevo shortcode:

[blockAlert css="alert alert-warning" style="border: 1px solid #f59e0b; padding: 10px;"]
Recuerda revisar los datos antes de confirmar.
[/blockAlert]

El nombre debe mantener la correspondencia AlertBlock → [blockAlert]. El método fromShortcode() recibe los atributos como array y el contenido interno como texto.