Enviar emails con NewMail

Podemos enviar emails desde FacturaScripts utilizando la clase NewMail. Este clase facilita el envío de emails desde FacturaScripts. Utiliza los datos del correo configurado 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 de un correo electrónico a otras personas además del destinatario principal. Las personas que se incluyen en el campo CC reciben una copia del mensaje, pero no se consideran destinatarios principales.

El campo CC se puede utilizar para varios propósitos, entre los que se incluyen:

Mantener a otros informados de un correo electrónico. Por ejemplo, si envías un correo electrónico a un cliente, puedes incluir a tu gerente en el campo CC para que esté al tanto de la conversación.
Obtener comentarios de otras personas. Si estás trabajando en un proyecto, puedes enviar un correo electrónico a tus compañeros de equipo en el campo CC para obtener su opinión.
Remitir un correo electrónico a otras personas. Si recibes un correo electrónico que crees que puede ser útil para otras personas, puedes reenviarlo en el campo CC.

$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, que significa "con copia oculta", se utiliza para enviar una copia de un correo electrónico a otras personas sin que los demás destinatarios puedan ver sus direcciones de correo electrónico.

El campo BCC se puede utilizar para varios propósitos, entre los que se incluyen:

Proteger la privacidad de las direcciones de correo electrónico. Por ejemplo, si estás enviando un correo electrónico a un grupo de personas, puedes utilizar el campo BCC para ocultar las direcciones de correo electrónico de los demás destinatarios.
Enviar un correo electrónico a un grupo grande de personas sin abrumar a los destinatarios principales. Si estás enviando un correo electrónico a un grupo grande de personas, puedes utilizar el campo BCC para evitar que los destinatarios principales reciban una respuesta de todos los demás destinatarios.
Enviar un correo electrónico a personas que no se conocen entre sí. Si estás enviando un correo electrónico a personas que no se conocen entre sí, puedes utilizar el campo BCC para evitar que conozcan las direcciones de correo electrónico de los demás.

$mail = NewMail::create()
    ->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, en lugar de escribir todo el texto cada vez, podemos preparar una notificación con el texto precargado (que además podrá modificar el usuario).

📝 Cómo crear una notificación

Para crear la notificación usaremos el modelo MailNotification:

$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á reemplazado por el nombre del contacto o cliente al que enviemos el email.

📨 Cómo enviar un notificación de email

Para enviar la notificación simplemente debemos llamar a la clase MailNotifier:

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

Si hemos incluído otras cadenas de texto a reemplazar en el email, por ejemplo una fecha de vencimiento y un nombre de proyecto, podemos incluir esos valores a reemplazar en los parámetros.

// Si el texto de la notificación es "Hola {name}, la fecha de vencimiento del proyecto {project} es {expiration}"
// Podemos enviar la notificación así

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, etc ... Tenemos unos textos predeterminados para esos emails, que realmente son notificaciones: sendmail-AlbaranCliente, sendmail-FacturaCliente ... puedes conseguir el mismo comportamiento con tus modelos simplemente creando una notificación para cada uno con el prefijo sendmail-.

Shortcodes

Puedes aprender sobre el uso de los shortcodes de aquí.

NewMail parsea shortcodes y crea bloques nativos para:

blockTitle -> TitleBlock
blockText -> TextBlock
blockHtml -> HtmlBlock
blockButton -> ButtonBlock
blockSpace -> SpaceBlock
blockBox -> BoxBlock
blockSpace -> SpaceBlock
Usarlos directamente por código PHP.
Exponerlos como shortcodes personalizados con NewMail::addBlockHandler().

Ejemplo de BoxBlock (uso por código)

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 (array): lista de bloques hijos (BaseBlock[]).
$css (opcional): clase CSS del contenedor.
$style (opcional): reservado para extensiones; el render nativo no lo aplica directamente.

Ejemplo de TableBlock (uso por código)

use FacturaScripts\Core\Lib\Email\TableBlock;

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

$mail->addMainBlock($table);

Parámetros de TableBlock:

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

Ejemplo de BoxBlock como shortcode personalizado

Registro del handler:

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

NewMail::addBlockHandler('box', function (array $attrs, string $content) {
  return new BoxBlock(
    [new TextBlock($content)],
    $attrs['css'] ?? '',
    $attrs['style'] ?? ''
  );
});

Uso del shortcode con todos los parámetros:

[blockBox css="block mb-15" style="border:1px solid #d1d5db;padding:12px;"]
Este texto se renderiza dentro de una caja.
[/blockBox]

Ejemplo de TableBlock como shortcode personalizado

Registro del handler:

use FacturaScripts\Core\Lib\Email\NewMail;
use FacturaScripts\Core\Lib\Email\TableBlock;

NewMail::addBlockHandler('table', function (array $attrs, string $content) {
  $header = isset($attrs['header']) ? explode('|', $attrs['header']) : [];
  $rows = [];

  if (!empty($attrs['rows'])) {
    foreach (explode(';', $attrs['rows']) as $line) {
      $rows[] = explode(',', $line);
    }
  }

  return new TableBlock(
    $header,
    $rows,
    $attrs['css'] ?? '',
    $attrs['style'] ?? ''
  );
});

Uso del shortcode con todos los parámetros:

[blockTable header="Producto|Cantidad|Precio" rows="Teclado,2,29.90 EUR;Raton,1,19.90 EUR" css="table mb-15 w-100" style="font-size:13px;"]

Ejemplo completo: crear y añadir tu propio shortcode

Este ejemplo crea un bloque personalizado AlertBlock, lo registra como shortcode blockAlert y muestra cómo usarlo en el cuerpo del email.

Crear la clase del bloque.

namespace MiPlugin\Lib\Email;

use FacturaScripts\Core\Lib\Email\BaseBlock;

class AlertBlock extends BaseBlock
{
  private $text;

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

  public function render(bool $footer = false): string
  {
    return '<div class="' . (empty($this->css) ? 'alert' : $this->css) . '">' . $this->text . '</div>';
  }
}

Registrar el shortcode en el arranque de tu plugin.

use FacturaScripts\Core\Lib\Email\NewMail;
use MiPlugin\Lib\Email\AlertBlock;

NewMail::addBlockHandler('alert', function (array $attrs, string $content) {
  return new AlertBlock(
    $content,
    $attrs['css'] ?? '',
    $attrs['style'] ?? ''
  );
});

Usar el shortcode en el texto del correo.

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

Parámetros del shortcode blockAlert en este ejemplo:

css (opcional): clase CSS del bloque.
style (opcional): atributo disponible para tu implementación.
Contenido interno (obligatorio en este ejemplo): texto que se renderiza dentro de la alerta.

Resumen rápido de bloques

Nativos por shortcode: TitleBlock, TextBlock, HtmlBlock, ButtonBlock, SpaceBlock, BoxBlock, TableBlock.
Ampliables por plugin: cualquier bloque propio mediante addBlockHandler().