Instalación y configuración rápida

Requisitos del entorno

• Versión de PHP 7.3, 7.4, 8.0 o 8.1
• Herramienta de gestión de dependencias Composer
• Clave API de SendGrid (disponible en el panel de control de SendGrid)

Método de instalación

Instalación mediante Composer:

composer require sendgrid/sendgrid

Opcionalmente, declare la depenedncia en su archivo composer.json:

{
"require": {
"sendgrid/sendgrid": "~7"
}
}

Configuración de la clave API

Establezca la clave API como variable de entorno:

export SENDGRID_API_KEY='SU_CLAVE_API'

Acceda a la clave desde el código PHP:

$claveAPI = getenv('SENDGRID_API_KEY');
$clienteSendGrid = new \SendGrid($claveAPI);

Ejemplo básico de envío de correo

<?php
require 'vendor/autoload.php';
use SendGrid\Mail\Mail;

$correo = new Mail();
$correo->setFrom("test@example.com", "Remitente");
$correo->setSubject("Asunto de prueba");
$correo->addTo("destinatario@example.com", "Destinatario");
$correo->addContent("text/plain", "Contenido en texto plano");
$correo->addContent("text/html", "<strong>Contenido HTML</strong>");

$cliente = new \SendGrid(getenv('SENDGRID_API_KEY'));

try {
$response = $cliente->send($correo);
echo "Código de estado: " . $response->statusCode() . "\n";
echo "Respuesta: " . $response->body() . "\n";
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage() . "\n";
}

Funcionalidades avanzadas

Personalización de correos

$correo = new Mail();
$correo->setFrom("empresa@example.com", "Tu Empresa");

// Destinatarios múltiples
$correo->addTo("cliente1@example.com", "Cliente 1");
$correo->addTo("cliente2@example.com", "Cliente 2");

// Copias y copias ocultas
$correo->addCc("copia@example.com", "Copia");
$correo->addBcc("copiaoculta@example.com", "Copia Oculta");

Envío con archivos adjuntos

$archivoCodificado = base64_encode(file_get_contents('informe.pdf'));
$correo->addAttachment(
$archivoCodificado,
"application/pdf",
"informe.pdf",
"attachment"
);

Plantillas dinámicas

$correo->setTemplateId("d-plantilla-001");
$correo->addDynamicTemplateData("nombre", "Juan Pérez");
$correo->addDynamicTemplateData("pedido", "PED-2023-001");

Configuraciones técnicas

Modo de pruebas (sandbox)

$configuracionCorreo = new MailSettings();
$modoPruebas = new SandBoxMode(true);
$configuracionCorreo->setSandboxMode($modoPruebas);
$correo->setMailSettings($configuracionCorreo);

Seguimiento de interacciones

$seguimiento = new TrackingSettings();

// Seguimiento de clics
$seguimientoClics = new ClickTracking();
$seguimientoClics->setEnable(true);
$seguimiento->setClickTracking($seguimientoClics);

// Seguimiento de aperturas
$seguimientoAperturas = new OpenTracking();
$seguimientoAperturas->setEnable(true);
$seguimiento->setOpenTracking($seguimientoAperturas);

$correo->setTrackingSettings($seguimiento);

Envío masivo de correos

try {
$response = $cliente->client->mail()->batch()->post();
$idLote = json_decode($response->body())->batch_id;

$correo->setBatchId($idLote);
$response = $cliente->send($correo);
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage() . "\n";
}

Prácticas de seguridad

• Evite almacenar claves API en el código
• Utilice variables de entorno o servicios de gestión de secretos
• Valide direcciones de correo con FILTER_VALIDATE_EMAIL
• Actualice regularmente la biblioteca y sus claves API

Manejo de errores y depuración

try {
$response = $cliente->send($correo);
if ($response->statusCode() >= 200 && $response->statusCode() < 300) {
echo "Correo enviado exitosamente\n";
} else {
echo "Fallo en envío. Código: " . $response->statusCode() . "\n";
echo "Detalles: " . $response->body() . "\n";
}
} catch (\Exception $e) {
echo "Excepción: " . $e->getMessage() . "\n";
}

Optimización de rendimiento

Conexiones persistentes

$opciones = [
'curl' => [
CURLOPT_TCP_KEEPALIVE => 1,
CURLOPT_TCP_KEEPIDLE => 120,
CURLOPT_TCP_KEEPINTVL => 60
]
];
$cliente = new \SendGrid($claveAPI, $opciones);

Envío asíncrono

// Cola de tareas
$cola->push(new TareaCorreo($datosCorreo));

// Procesamiento en segundo plano
class TareaCorreo {
public function handle() {
$cliente = new \SendGrid(getenv('SENDGRID_API_KEY'));
$cliente->send($this->correo);
}
}

Escenarios de uso comunes

Confirmación de rgeistro

$correo = new Mail();
$correo->setFrom("no-responder@app.com", "Mi Aplicación");
$correo->setSubject("Confirme su dirección de correo");
$correo->addTo($emailUsuario, $nombreUsuario);
$correo->addContent("text/html", $this->generarCorreoConfirmacion($usuario, $enlace));

Restablecimiento de contraseña

$correo = new Mail();
$correo->setFrom("soporte@app.com", "Equipo de Soporte");
$correo->setSubject("Solicitud de restablecimiento");
$correo->addTo($emailUsuario);
$correo->addContent("text/html", $this->generarCorreoRestablecer($enlace));

Monitoreo y registro

Estadísticas de envío

$response = $cliente->client->mail()->send()->get();
$estadisticas = json_decode($response->body());
echo "Éxitos: " . $estadisticas->success . "\n";
echo "Errores: " . $estadisticas->errors . "\n";

Integración con sistema de logs

$logger = new Logger('sendgrid');
$logger->pushHandler(new StreamHandler('logs/sendgrid.log', Logger::INFO));

try {
$response = $cliente->send($correo);
$logger->info('Correo enviado', [
'to' => $destinatario,
'id' => $response->headers()['X-Message-Id'] ?? null
]);
} catch (\Exception $e) {
$logger->error('Fallo en envío', [
'to' => $destinatario,
'error' => $e->getMessage()
]);
}

Prácticas recomendadas

• Almaceen claves API en variables de entorno
• Valide todas las entradas críticas
• Use plantillas para mayor eficiencia
• Implemente manejo de errores y registros
• Monitoree estadísticas de envío
• Mantenga actualizada la biblioteca