Tutorial

Enviar emails con Java

Envía emails desde Java con el SDK emailit-java o con Spring Boot y Jakarta Mail por SMTP, y verifica los webhooks de Emailit en un controlador de Spring.

Actualizado el 1 oct 2026

En esta guía se explica cómo enviar emails desde Java con el SDK oficial emailit-java, cómo usar en su lugar el starter de correo de Spring Boot o Jakarta Mail por SMTP y cómo verificar los webhooks en un controlador de Spring.

Requisitos previos

Java 11 o posterior. Los ejemplos de Spring usan Spring Boot 3, que requiere Java 17.
Un dominio de envío verificado, por ejemplo acme.com.
Una clave de API. Basta con una clave Sending Only limitada a tu dominio.
Hasta que tu espacio de trabajo tenga acceso de producción, solo puedes enviar a las direcciones de email de las cuentas de los miembros del espacio de trabajo.

Instalar el SDK

Añade la dependencia con la última versión del repositorio emailit-java:

pom.xml

<dependency>
  <groupId>com.emailit</groupId>
  <artifactId>emailit-java</artifactId>
  <version>VERSION</version>
</dependency>

build.gradle

implementation 'com.emailit:emailit-java:VERSION'

Configurar la clave de API

Proporciona la clave como variable de entorno:

Terminal

export EMAILIT_API_KEY=secret_••••••••••••••••••••••••••••••••

En Spring Boot, asígnala a una propiedad para poder inyectarla:

application.properties

emailit.api-key=${EMAILIT_API_KEY}

Enviar un email

SendEmail.java

import com.emailit.*;
import com.emailit.exception.*;
import com.emailit.params.*;
import java.util.List;

public class SendEmail {
    public static void main(String[] args) throws EmailitException {
        EmailitClient emailit = new EmailitClient(System.getenv("EMAILIT_API_KEY"));

        EmailSendParams params = EmailSendParams.builder()
            .setFrom("Acme <hello@acme.com>")
            .setTo(List.of("ada@example.com"))
            .setSubject("Your order has shipped")
            .setHtml("<p>Order #1042 is on its way.</p>")
            .build();

        EmailitObject email = emailit.emails().send(params);
        System.out.println(email.getString("id")); // em_…
    }
}

En Spring Boot, registra el cliente una sola vez como bean e inyéctalo donde envíes:

EmailitConfig.java

import com.emailit.EmailitClient;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class EmailitConfig {
    @Bean
    EmailitClient emailitClient(@Value("${emailit.api-key}") String apiKey) {
        return new EmailitClient(apiKey);
    }
}

Gestionar los errores

El SDK lanza excepciones tipadas que extienden EmailitException:

Java

try {
    emailit.emails().send(params);
} catch (RateLimitException e) {
    // 429: back off and retry
} catch (AuthenticationException e) {
    // 401: the API key is missing or invalid
} catch (UnprocessableEntityException e) {
    // 422: for example, the from domain isn't verified
} catch (EmailitException e) {
    log.error("Emailit error {}: {}", e.getHttpStatus(), e.getHttpBody());
}

Enviar por SMTP

Spring Boot

Añade spring-boot-starter-mail y configura el relay:

application.properties

spring.mail.host=smtp.emailit.com
spring.mail.port=587
spring.mail.username=emailit
spring.mail.password=${EMAILIT_API_KEY}
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.starttls.required=true

Después, envía con JavaMailSender:

WelcomeMailer.java

import org.springframework.mail.SimpleMailMessage;
import org.springframework.mail.javamail.JavaMailSender;
import org.springframework.stereotype.Service;

@Service
public class WelcomeMailer {
    private final JavaMailSender mailSender;

    public WelcomeMailer(JavaMailSender mailSender) {
        this.mailSender = mailSender;
    }

    public void sendWelcome(String to) {
        SimpleMailMessage message = new SimpleMailMessage();
        message.setFrom("Acme <hello@acme.com>");
        message.setTo(to);
        message.setSubject("Welcome to Acme");
        message.setText("Thanks for signing up.");
        mailSender.send(message);
    }
}

Usa MimeMessageHelper para HTML y adjuntos.

Jakarta Mail sin Spring

Jakarta Mail sin más (antes JavaMail) usa las mismas propiedades mail.smtp.*:

Java

Properties props = new Properties();
props.put("mail.smtp.host", "smtp.emailit.com");
props.put("mail.smtp.port", "587");
props.put("mail.smtp.auth", "true");
props.put("mail.smtp.starttls.enable", "true");
props.put("mail.smtp.starttls.required", "true");

Session session = Session.getInstance(props, new Authenticator() {
    @Override
    protected PasswordAuthentication getPasswordAuthentication() {
        return new PasswordAuthentication("emailit", System.getenv("EMAILIT_API_KEY"));
    }
});

Si el puerto 587 está bloqueado en tu red, usa el 2525 o el 2587 con la misma configuración. Consulta Configuración SMTP.

Recibir webhooks

Crea un webhook y guarda su secreto de firma en EMAILIT_WEBHOOK_SECRET. Recibe el cuerpo como String para verificar exactamente lo que firmó Emailit:

EmailitWebhookController.java

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
public class EmailitWebhookController {
    private final ObjectMapper mapper = new ObjectMapper();
    private final String secret = System.getenv("EMAILIT_WEBHOOK_SECRET");

    @PostMapping("/webhooks/emailit")
    public ResponseEntity<Void> receive(
            @RequestBody String body,
            @RequestHeader(value = "X-Emailit-Signature", defaultValue = "") String signature,
            @RequestHeader(value = "X-Emailit-Timestamp", defaultValue = "0") long timestamp) throws Exception {

        if (Math.abs(System.currentTimeMillis() / 1000 - timestamp) > 300 || !isValid(body, signature, timestamp)) {
            return ResponseEntity.status(401).build();
        }

        // The body is a JSON array of up to 100 events.
        for (JsonNode event : mapper.readTree(body)) {
            if ("email.bounced".equals(event.path("type").asText())) {
                String address = event.path("data").path("object").path("to").asText();
                // Stop emailing this address.
            }
        }
        return ResponseEntity.ok().build();
    }

    private boolean isValid(String body, String signature, long timestamp) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        byte[] digest = mac.doFinal((timestamp + "." + body).getBytes(StandardCharsets.UTF_8));
        String expected = HexFormat.of().formatHex(digest);
        return MessageDigest.isEqual(
            expected.getBytes(StandardCharsets.UTF_8),
            signature.getBytes(StandardCharsets.UTF_8));
    }
}

Si Spring Security está activado, permite esta ruta y exclúyela de la protección CSRF. Devuelve un 2xx en menos de 30 segundos; las demás respuestas se reintentan. Consulta Firma de las peticiones.

Consejos para producción

Reutiliza los clientes. Crea un único EmailitClient (o usa el JavaMailSender único de Spring) en lugar de uno por mensaje.
Envía de forma asíncrona. Usa @Async, una cola de mensajes o una tarea programada para los envíos masivos, y limita el ritmo para no superar tus límites de envío (2 emails por segundo por defecto).
Haz que los reintentos sean seguros. Si reintentas después de que se agote el tiempo de espera, envía una cabecera Idempotency-Key con java.net.http.HttpClient; consulta Idempotencia.
Elimina los webhooks duplicados guardando cada event_id que procesas.

Próximos pasos

Enviar emails con la API

Adjuntos, programación y seguimiento.

Tipos de eventos de webhook

Todos los eventos y su payload.

Solución de problemas de SMTP

Corrige los errores de autenticación y de conexión.

SDK y bibliotecas

Todas las bibliotecas oficiales.