Tutoriel

Envoyer des e-mails avec Java

Envoyez des e-mails depuis Java avec le SDK emailit-java, ou avec Spring Boot et Jakarta Mail via SMTP, et vérifiez les webhooks Emailit dans un contrôleur Spring.

Mis à jour le 1 oct. 2026

Ce guide montre comment envoyer des e-mails depuis Java avec le SDK officiel emailit-java, comment utiliser plutôt le starter mail de Spring Boot ou Jakarta Mail via SMTP, et comment vérifier les webhooks dans un contrôleur Spring.

Prérequis

Java 11 ou version ultérieure. Les exemples Spring utilisent Spring Boot 3, qui nécessite Java 17.
Un domaine d’envoi vérifié, par exemple acme.com.
Une clé API. Une clé Sending Only limitée à votre domaine suffit.
Tant que votre espace de travail n’a pas l’accès production, vous ne pouvez envoyer qu’aux adresses e-mail des comptes des membres de l’espace de travail.

Installer le SDK

Ajoutez la dépendance, avec la dernière version indiquée dans le dépôt 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'

Configurer votre clé API

Fournissez la clé dans une variable d’environnement :

Terminal

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

Dans Spring Boot, associez-la à une propriété pour pouvoir l’injecter :

application.properties

emailit.api-key=${EMAILIT_API_KEY}

Envoyer un e-mail

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_…
    }
}

Dans Spring Boot, enregistrez le client une seule fois comme bean et injectez-le là où vous envoyez :

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);
    }
}

Gérer les erreurs

Le SDK lève des exceptions typées qui étendent 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());
}

Envoyer plutôt via SMTP

Spring Boot

Ajoutez spring-boot-starter-mail et configurez le relais :

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

Envoyez ensuite avec 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);
    }
}

Utilisez MimeMessageHelper pour le HTML et les pièces jointes.

Jakarta Mail sans Spring

Jakarta Mail seul (anciennement JavaMail) utilise les mêmes propriétés 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 le port 587 est bloqué sur votre réseau, utilisez 2525 ou 2587 avec les mêmes paramètres. Consultez Paramètres SMTP.

Recevoir des webhooks

Créez un webhook et enregistrez son secret de signature dans EMAILIT_WEBHOOK_SECRET. Recevez le corps sous forme de String pour vérifier exactement ce qu’Emailit a signé :

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 activé, autorisez ce chemin et excluez-le de la protection CSRF. Renvoyez un 2xx dans les 30 secondes ; pour toute autre réponse, Emailit réessaie. Consultez Signature des requêtes.

Conseils pour la production

Réutilisez les clients. Créez un seul EmailitClient (ou appuyez-vous sur l’unique JavaMailSender de Spring) plutôt qu’un par message.
Envoyez de façon asynchrone. Utilisez @Async, une file de messages ou une tâche planifiée pour les envois en masse, et limitez le débit pour rester sous vos limites d’envoi (2 e-mails par seconde par défaut).
Sécurisez les relances. Si vous relancez une requête après un timeout, envoyez un en-tête Idempotency-Key avec java.net.http.HttpClient ; consultez Idempotence.
Dédoublonnez les webhooks en enregistrant chaque event_id traité.

Étapes suivantes

Envoyer des e-mails avec l’API

Pièces jointes, programmation et suivi.

Types d’événements webhook

Tous les événements et leur payload.

Dépannage SMTP

Corrigez les erreurs d’authentification et de connexion.

SDK et bibliothèques

Toutes les bibliothèques officielles.