Java SDK

The official Java SDK for Veil Mail with idiomatic Java patterns.

Exception-based error handling
Maven and Gradle support
Constant-time HMAC webhook verification
Java 11+ compatible (HttpURLConnection)
Jackson JSON serialization

Installation

Maven

<dependency>
    <groupId>xyz.veilmail</groupId>
    <artifactId>veilmail-java</artifactId>
    <version>0.1.0</version>
</dependency>

Gradle

implementation 'xyz.veilmail:veilmail-java:0.1.0'

Quick Start

App.java

import xyz.veilmail.sdk.VeilMail;
import java.util.Map;

VeilMail client = new VeilMail("veil_live_xxxxx");

Map<String, Object> email = client.emails().send(Map.of(
    "from", "hello@yourdomain.com",
    "to", "user@example.com",
    "subject", "Hello from Java!",
    "html", "<h1>Welcome!</h1>"
));

System.out.println(email.get("id"));     // email_xxxxx
System.out.println(email.get("status")); // queued

Resources

The client exposes the same resources as the Node.js SDK:

Resource	Description
`client.emails()`	Send, batch send, list, get, cancel, update emails
`client.domains()`	Create, verify, update, list, delete domains
`client.templates()`	Create, update, preview, list, delete templates
`client.audiences()`	Manage audiences and subscribers
`client.campaigns()`	Create, schedule, send, pause, resume, cancel campaigns
`client.webhooks()`	Manage webhook endpoints, test, rotate secrets
`client.topics()`	Manage subscription topics and preferences
`client.properties()`	Manage contact property definitions and values

Error Handling

ErrorHandling.java

import xyz.veilmail.sdk.exceptions.*;

try {
    client.emails().send(Map.of(
        "from", "hello@yourdomain.com",
        "to", "user@example.com",
        "subject", "Hello",
        "html", "<p>Hi!</p>"
    ));
} catch (RateLimitException e) {
    System.out.println("Rate limited. Retry after " + e.getRetryAfter() + "s");
} catch (PiiDetectedException e) {
    System.out.println("PII detected: " + e.getPiiTypes());
} catch (ValidationException e) {
    System.out.println("Validation error: " + e.getMessage());
} catch (AuthenticationException e) {
    System.out.println("Invalid API key");
} catch (VeilMailException e) {
    System.out.println("API error: " + e.getMessage());
}

Webhook Verification

Use the built-in utility to verify webhook signatures in Spring:

WebhookController.java

import xyz.veilmail.sdk.Webhook;

@PostMapping("/webhooks/veilmail")
public ResponseEntity<Void> handleWebhook(
        @RequestBody String body,
        @RequestHeader("X-Signature-Hash") String signature) {

    if (!Webhook.verifySignature(body, signature, webhookSecret)) {
        return ResponseEntity.status(401).build();
    }

    ObjectMapper mapper = new ObjectMapper();
    Map<String, Object> event = mapper.readValue(body, Map.class);

    switch ((String) event.get("type")) {
        case "email.delivered":
            // Handle delivery
            break;
        case "email.bounced":
            // Handle bounce
            break;
    }

    return ResponseEntity.ok().build();
}

Required Scopes

The Java SDK uses the same API scopes as the Authentication system. See the Node.js SDK documentation for the full scope reference.