Send email from Java with one HTTP call.

package com.acme.mail;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.annotation.JsonInclude;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.Map;

@Component
public class NotixClient {

    // Records are the payload; Jackson writes them as camelCase JSON, which
    // is what the API reads. Nulls are dropped so optional fields stay out.
    @JsonInclude(JsonInclude.Include.NON_NULL)
    public record SendEmail(String from, String to, String subject,
                            String html, String text,
                            String templateId, Map<String, String> variables) {}

    public record Sent(String emailId) {}
    public record ApiError(String code, String message) {}
    record ErrorEnvelope(ApiError error) {}

    public sealed interface Result permits Ok, Refused {}
    public record Ok(Sent sent) implements Result {}
    public record Refused(int status, ApiError error) implements Result {}

    private final HttpClient http = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(5))
            .build();
    private final ObjectMapper json = new ObjectMapper();
    private final String apiKey;
    private final String baseUrl;

    public NotixClient(@Value("${notix.api-key}") String apiKey,
                       @Value("${notix.base-url}") String baseUrl) {
        this.apiKey = apiKey;
        this.baseUrl = baseUrl;
    }

    public Result send(SendEmail email, String idempotencyKey) throws Exception {
        HttpRequest request = HttpRequest.newBuilder(URI.create(baseUrl + "/emails"))
                .timeout(Duration.ofSeconds(10))
                .header("Authorization", "Bearer " + apiKey)
                .header("Content-Type", "application/json")
                // One key per business event, so a retry can never send twice.
                .header("Idempotency-Key", idempotencyKey)
                .POST(HttpRequest.BodyPublishers.ofString(json.writeValueAsString(email)))
                .build();

        HttpResponse<String> response = http.send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() / 100 == 2) {
            return new Ok(json.readValue(response.body(), Sent.class));
        }
        // Every refusal is { "error": { "code", "message" } }; a 413 for a
        // body over 20 MB is the one answer with no JSON.
        ApiError error = response.body().isBlank()
                ? new ApiError("HTTP_" + response.statusCode(), "No error body")
                : json.readValue(response.body(), ErrorEnvelope.class).error();
        return new Refused(response.statusCode(), error);
    }
}

package com.acme.mail;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

@RestController
public class ReceiptController {

    private final NotixClient notix;

    public ReceiptController(NotixClient notix) {
        this.notix = notix;
    }

    @PostMapping("/orders/{orderId}/receipt")
    public ResponseEntity<?> sendReceipt(@PathVariable String orderId) throws Exception {
        var email = new NotixClient.SendEmail(
                "receipts@acme.com",
                "customer@example.com",
                "Your receipt for order " + orderId,
                "<p>Thanks for your order.</p>",
                "Thanks for your order.",
                null, null);

        return switch (notix.send(email, "order-" + orderId + "-receipt")) {
            case NotixClient.Ok ok ->
                    ResponseEntity.ok(Map.of("emailId", ok.sent().emailId()));
            case NotixClient.Refused refused ->
                    ResponseEntity.status(502).body(refused.error());
        };
    }
}

curl -X POST https://app.usenotix.dev/api/v1/emails \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Idempotency-Key: order-4471-receipt" \
  -H "Content-Type: application/json" \
  -d '{ "from": "receipts@acme.com", "to": "customer@example.com",
        "subject": "Your receipt for order 4471",
        "html": "<p>Thanks for your order.</p>", "text": "Thanks for your order." }'

# 200 { "emailId": "eml_abc123" }
# 400 { "error": { "code": "BAD_REQUEST",   "message": "..." } }   your request
# 401 { "error": { "code": "UNAUTHORIZED",  "message": "..." } }   bad or missing key
# 409 { "error": { "code": "NOT_UNIQUE",    "message": "..." } }   same key, different body
# 429 { "error": { "code": "RATE_LIMITED",  "message": "Rate limit exceeded. Try again in 60 seconds." } }