Tutoriál

Odesílání e-mailů z Javy

Odesílejte e-maily z Javy přes SDK emailit-java, nebo přes SMTP se Spring Bootem a Jakarta Mail, a ověřujte webhooky Emailitu ve Spring controlleru.

Aktualizováno 1. 10. 2026

Tento návod ukazuje, jak odesílat e-maily z Javy přes oficiální SDK emailit-java, jak místo toho použít mail starter Spring Bootu nebo Jakarta Mail přes SMTP a jak ověřovat webhooky ve Spring controlleru.

Předpoklady

Java 11 nebo novější. Příklady pro Spring používají Spring Boot 3, který potřebuje Javu 17.
Ověřená odesílací doména, například acme.com.
API klíč. Stačí klíč jen pro odesílání omezený na vaši doménu.
Dokud váš workspace nemá produkční přístup, můžete odesílat jen na e-mailové adresy účtů členů workspace.

Nainstalujte SDK

Přidejte závislost v nejnovější verzi z repozitáře 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'

Nastavte API klíč

Předejte klíč jako proměnnou prostředí:

Terminal

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

Ve Spring Bootu ho namapujte na vlastnost, abyste ho mohli vkládat:

application.properties

emailit.api-key=${EMAILIT_API_KEY}

Odešlete 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_…
    }
}

Ve Spring Bootu zaregistrujte klienta jednou jako bean a vkládejte ho tam, kde odesíláte:

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

Ošetřete chyby

SDK vyhazuje typované výjimky, které rozšiřují 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());
}

Odesílání přes SMTP

Spring Boot

Přidejte spring-boot-starter-mail a nastavte SMTP 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

Pak odesílejte přes 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);
    }
}

Pro HTML a přílohy použijte MimeMessageHelper.

Jakarta Mail bez Springu

Samotný Jakarta Mail (dříve JavaMail) používá stejné vlastnosti 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"));
    }
});

Pokud je ve vaší síti port 587 blokovaný, použijte se stejným nastavením port 2525 nebo 2587. Viz Nastavení SMTP.

Přijímejte webhooky

Vytvořte webhook a jeho tajný klíč uložte do EMAILIT_WEBHOOK_SECRET. Tělo přijímejte jako String, abyste ověřovali přesně to, co Emailit podepsal:

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

Pokud máte zapnuté Spring Security, tuto cestu povolte a vyjměte ji z ochrany CSRF. Do 30 sekund vraťte 2xx; při jiných odpovědích se požadavek opakuje. Viz Ověření podpisu webhooků.

Tipy pro produkční provoz

Používejte klienty opakovaně. Vytvořte jeden EmailitClient (nebo se spolehněte na jediný JavaMailSender ve Springu), ne jeden pro každou zprávu.
Odesílejte asynchronně. Pro hromadnou poštu použijte @Async, frontu zpráv nebo plánovanou úlohu a omezte propustnost, abyste zůstali pod svými limity odesílání (ve výchozím stavu 2 e-maily za sekundu).
Zajistěte bezpečné opakování. Pokud po vypršení časového limitu požadavek opakujete, pošlete s java.net.http.HttpClient hlavičku Idempotency-Key; viz Idempotentní požadavky.
Odstraňujte duplicitní webhooky tak, že si uložíte každé zpracované event_id.

Další kroky

Odesílání e-mailů přes API

Přílohy, plánování a měření.

Typy událostí webhooků

Všechny události a jejich obsah.

Řešení problémů se SMTP

Opravte chyby autentizace a připojení.

SDK a knihovny

Všechny oficiální knihovny.