diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c5a721..234fed8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.2.0] - 2026-09-14 + +### Added + +- `campaigns()`: `createDraft`, `createAndSend`, `list`, `listForStream`, + `get`, `getForStream`, `update`, `send`, `cancel`. The two create methods + hit different routes: `createDraft` writes the campaign and waits, while + `createAndSend` expands it to the stream's subscribers before the call + returns. +- `subscribers()`: `list`, `add`, `importAddresses`, `complaint`, `remove`. +- `layouts()`: `list`, `create`, `get`, `update`, `delete`, `uploadLogo`. +- `inbound()`: `list`, `get`, `retry`, `bypass`. +- `logs()`: `list`, `tags`. +- `emails().sendToStream()` for broadcasting to a stream's subscribers. +- An idempotency-key overload on all four send methods. The key travels as + the `Idempotency-Key` header, because the body is what the server hashes + to recognise a replay. +- `StreamRequest` takes a `permalink` and an `archived` flag. Without the + permalink the API derives one from the name, which a caller that has to + know the permalink up front cannot rely on. + ## [0.1.0] - 2026-07-12 ### Added @@ -22,5 +43,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `dmarc()`: `summary`, `reports`, `report`. - Typed, unchecked `CamelMailerException` with stable API error `code` and HTTP `statusCode`. -[Unreleased]: https://github.com/camelmailer/camelmailer-java/compare/v0.1.0...HEAD +[Unreleased]: https://github.com/camelmailer/camelmailer-java/compare/v0.2.0...HEAD +[0.2.0]: https://github.com/camelmailer/camelmailer-java/releases/tag/v0.2.0 [0.1.0]: https://github.com/camelmailer/camelmailer-java/releases/tag/v0.1.0 diff --git a/README.md b/README.md index 279925d..eb44528 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,22 @@ client.emails().sendWithTemplate( .build()); client.emails().sendWithTemplateBatch(List.of(...)); +// Retry-safe sends: the same key with the same body returns the first +// result instead of queuing a second copy, and a different body under the +// same key is refused with InvalidIdempotentRequest. All four send methods +// take one. +client.emails().send(request, "order-" + orderId); + +// Broadcast to everyone subscribed to a stream. Recipients past the +// per-request cap of 1000 come back as skipped, so a larger audience wants +// a campaign. +StreamSendResult broadcast = client.emails().sendToStream("newsletter", + SendEmailRequest.builder() + .from("news@acme.com") + .subject("September") + .textBody("What shipped this month.") + .build()); + // Read back EmailDetails details = client.emails().get(messageId); // message + deliveries EmailList page = client.emails().list( @@ -104,12 +120,109 @@ RenderedTemplate preview = client.templates().render("welcome", Map.of("name", " ```java client.streams().list(); -client.streams().create(StreamRequest.builder().name("Receipts").streamType("transactional").build()); +client.streams().create(StreamRequest.builder() + .name("Receipts").permalink("receipts").streamType("transactional").build()); client.streams().get("receipts"); client.streams().update("receipts", StreamRequest.builder().name("Billing").build()); client.streams().archive("receipts"); ``` +### Campaigns + +A campaign is content plus an audience. The two ways to create one behave +differently, so pick deliberately: `createDraft` writes it and waits, +`createAndSend` expands it to the stream's subscribers before the call +returns. + +```java +// Write it and leave it alone. Without a schedule it stays a draft; with +// one it becomes "scheduled" and the server sends it when due. +Campaign draft = client.campaigns().createDraft( + DraftCampaignRequest.builder() + .stream("newsletter") + .from("news@acme.com") + .name("September") + .subject("What shipped") + .textBody("Hello.") + // .scheduledAt("2026-10-01T08:00:00Z") + .build()); + +// Goes out on the spot, no draft and no schedule. +client.campaigns().createAndSend("newsletter", + SendCampaignRequest.builder() + .name("Status update") + .from("news@acme.com") + .textBody("All clear.") + .build()); + +client.campaigns().list(); +client.campaigns().listForStream("newsletter"); +CampaignDetail detail = client.campaigns().get(draft.id()); // campaign + stats + +// scheduledAt schedules; clearSchedule drops it back to a draft. Touching +// neither leaves the schedule standing, so the two are separate. +client.campaigns().update(draft.id(), + UpdateCampaignRequest.builder().scheduledAt("2026-10-01T08:00:00Z").build()); +client.campaigns().update(draft.id(), + UpdateCampaignRequest.builder().clearSchedule().build()); + +client.campaigns().send(draft.id()); // now, whatever the schedule said +client.campaigns().cancel(draft.id()); +``` + +### Subscribers + +A broadcast send to an address that is not subscribed is refused, so this +list is the audience. + +```java +client.subscribers().list("newsletter"); +client.subscribers().add("newsletter", + SubscriberRequest.builder().address("ada@example.com").name("Ada").build()); +client.subscribers().importAddresses("newsletter", + List.of("ada@example.com", "grace@example.com")); +client.subscribers().complaint("newsletter", "ada@example.com"); // suppress + unsubscribe +client.subscribers().remove("newsletter", "ada@example.com"); +``` + +### Layouts + +A layout wraps every template that uses it. `htmlWrapper` has to embed the +body with `{{{ content }}}`. + +```java +client.layouts().list(); +client.layouts().create(LayoutRequest.builder() + .name("Default") + .permalink("default") + .htmlWrapper("
{{{ content }}}") + .build()); +client.layouts().get("default"); +client.layouts().update("default", LayoutRequest.builder().name("Main").build()); +String logoUrl = client.layouts().uploadLogo("default", "data:image/png;base64,..."); +client.layouts().delete("default"); +``` + +### Inbound and held messages + +```java +InboundList held = client.inbound().list( + ListInboundOptions.builder().status("held").build()); +client.inbound().get(55); +client.inbound().retry(55); // back on the delivery queue +client.inbound().bypass(55); // release past the hold +``` + +### Logs + +Useful when a send did not arrive and the question is whether the request +ever reached the API. + +```java +LogList requests = client.logs().list(null, 25); +ListA campaign is content plus an audience. There are two ways to create one and they behave + * differently: {@link #createDraft} writes it and waits, while {@link #createAndSend} expands it to + * the stream's subscribers before the call returns. + * + *
Obtain via {@link com.camelmailer.CamelMailer#campaigns()}.
+ */
+public final class Campaigns {
+
+ private static final String BASE = "/api/v2/server/campaigns";
+ private static final String STREAMS = "/api/v2/server/streams";
+
+ private final ApiClient client;
+
+ /**
+ * Creates the service.
+ *
+ * @param client the internal API client
+ */
+ public Campaigns(ApiClient client) {
+ this.client = client;
+ }
+
+ /**
+ * Lists every campaign of the server, newest first.
+ *
+ * @return the campaigns
+ */
+ public List Name the audience with {@code stream}. Leave the schedule unset for a draft, set it for a
+ * scheduled send, or set {@code sendNow} to send on creation.
+ *
+ * @param request the campaign fields
+ * @return the created campaign
+ */
+ public Campaign createDraft(DraftCampaignRequest request) {
+ return client.convert(client.post(BASE, request).path("campaign"), Campaign.class);
+ }
+
+ /**
+ * Creates a campaign on a broadcast stream and sends it immediately.
+ *
+ * The send starts before this call returns, so there is no draft to review and no schedule to
+ * set. Use {@link #createDraft} when the campaign should wait.
+ *
+ * @param permalink the broadcast stream permalink
+ * @param request the campaign fields
+ * @return the created campaign, already sending
+ */
+ public Campaign createAndSend(String permalink, SendCampaignRequest request) {
+ JsonNode data = client.post(STREAMS + "/" + permalink + "/campaigns", request);
+ return client.convert(data.path("campaign"), Campaign.class);
+ }
+
+ /**
+ * Updates a draft or scheduled campaign.
+ *
+ * A campaign that is already sending cannot be edited and the API answers {@code
+ * ValidationError}.
+ *
+ * @param id the campaign id
+ * @param request the fields to change
+ * @return the updated campaign
+ */
+ public Campaign update(long id, UpdateCampaignRequest request) {
+ ObjectNode body = client.newObject();
+ putIfSet(body, "name", request.getName());
+ putIfSet(body, "from", request.getFrom());
+ putIfSet(body, "subject", request.getSubject());
+ putIfSet(body, "html_body", request.getHtmlBody());
+ putIfSet(body, "text_body", request.getTextBody());
+ if (request.isClearSchedule()) {
+ // An omitted field leaves the schedule standing; only an explicit
+ // null drops the campaign back to a draft.
+ body.putNull("scheduled_at");
+ } else {
+ putIfSet(body, "scheduled_at", request.getScheduledAt());
+ }
+ return client.convert(client.patch(BASE + "/" + id, body).path("campaign"), Campaign.class);
+ }
+
+ /**
+ * Sends a campaign now, whatever its schedule said.
+ *
+ * @param id the campaign id
+ * @return the campaign, now sending
+ */
+ public Campaign send(long id) {
+ return client.convert(
+ client.post(BASE + "/" + id + "/send", null).path("campaign"), Campaign.class);
+ }
+
+ /**
+ * Cancels a scheduled or in-flight campaign. Messages already queued are not recalled.
+ *
+ * @param id the campaign id
+ * @return the canceled campaign
+ */
+ public Campaign cancel(long id) {
+ return client.convert(
+ client.post(BASE + "/" + id + "/cancel", null).path("campaign"), Campaign.class);
+ }
+
+ private static void putIfSet(ObjectNode body, String field, String value) {
+ if (value != null) {
+ body.put(field, value);
+ }
+ }
+}
diff --git a/src/main/java/com/camelmailer/campaigns/DraftCampaignRequest.java b/src/main/java/com/camelmailer/campaigns/DraftCampaignRequest.java
new file mode 100644
index 0000000..1ef4f79
--- /dev/null
+++ b/src/main/java/com/camelmailer/campaigns/DraftCampaignRequest.java
@@ -0,0 +1,224 @@
+package com.camelmailer.campaigns;
+
+/**
+ * Fields for {@link Campaigns#createDraft}.
+ *
+ * The initial status follows what you pass: {@code sendNow} wins, then a {@code scheduledAt}
+ * (status {@code scheduled}), else a draft.
+ */
+public final class DraftCampaignRequest {
+
+ private final String stream;
+ private final String from;
+ private final String name;
+ private final String subject;
+ private final String htmlBody;
+ private final String textBody;
+ private final String scheduledAt;
+ private final Boolean sendNow;
+
+ private DraftCampaignRequest(Builder builder) {
+ this.stream = builder.stream;
+ this.from = builder.from;
+ this.name = builder.name;
+ this.subject = builder.subject;
+ this.htmlBody = builder.htmlBody;
+ this.textBody = builder.textBody;
+ this.scheduledAt = builder.scheduledAt;
+ this.sendNow = builder.sendNow;
+ }
+
+ /**
+ * Creates a new builder.
+ *
+ * @return a fresh builder
+ */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /**
+ * Returns the permalink of the broadcast stream to send to.
+ *
+ * @return the permalink of the broadcast stream to send to, or {@code null} when unset
+ */
+ public String getStream() {
+ return stream;
+ }
+
+ /**
+ * Returns the bare sender address.
+ *
+ * @return the bare sender address, or {@code null} when unset
+ */
+ public String getFrom() {
+ return from;
+ }
+
+ /**
+ * Returns the display name.
+ *
+ * @return the display name, or {@code null} when unset
+ */
+ public String getName() {
+ return name;
+ }
+
+ /**
+ * Returns the message subject.
+ *
+ * @return the message subject, or {@code null} when unset
+ */
+ public String getSubject() {
+ return subject;
+ }
+
+ /**
+ * Returns the HTML part.
+ *
+ * @return the HTML part, or {@code null} when unset
+ */
+ public String getHtmlBody() {
+ return htmlBody;
+ }
+
+ /**
+ * Returns the plain-text part.
+ *
+ * @return the plain-text part, or {@code null} when unset
+ */
+ public String getTextBody() {
+ return textBody;
+ }
+
+ /**
+ * Returns the RFC 3339 send time, which arms the campaign as scheduled.
+ *
+ * @return the RFC 3339 send time, which arms the campaign as scheduled, or {@code null} when
+ * unset
+ */
+ public String getScheduledAt() {
+ return scheduledAt;
+ }
+
+ /**
+ * Returns whether to send on creation, overriding the schedule.
+ *
+ * @return whether to send on creation, overriding the schedule, or {@code null} when unset
+ */
+ public Boolean getSendNow() {
+ return sendNow;
+ }
+
+ /** Builder for {@link DraftCampaignRequest}. */
+ public static final class Builder {
+
+ private String stream;
+ private String from;
+ private String name;
+ private String subject;
+ private String htmlBody;
+ private String textBody;
+ private String scheduledAt;
+ private Boolean sendNow;
+
+ private Builder() {}
+
+ /**
+ * Sets the permalink of the broadcast stream to send to (required).
+ *
+ * @param stream the permalink of the broadcast stream to send to
+ * @return this builder
+ */
+ public Builder stream(String stream) {
+ this.stream = stream;
+ return this;
+ }
+
+ /**
+ * Sets the bare sender address (required).
+ *
+ * @param from the bare sender address
+ * @return this builder
+ */
+ public Builder from(String from) {
+ this.from = from;
+ return this;
+ }
+
+ /**
+ * Sets the display name.
+ *
+ * @param name the display name
+ * @return this builder
+ */
+ public Builder name(String name) {
+ this.name = name;
+ return this;
+ }
+
+ /**
+ * Sets the message subject.
+ *
+ * @param subject the message subject
+ * @return this builder
+ */
+ public Builder subject(String subject) {
+ this.subject = subject;
+ return this;
+ }
+
+ /**
+ * Sets the HTML part.
+ *
+ * @param htmlBody the HTML part
+ * @return this builder
+ */
+ public Builder htmlBody(String htmlBody) {
+ this.htmlBody = htmlBody;
+ return this;
+ }
+
+ /**
+ * Sets the plain-text part.
+ *
+ * @param textBody the plain-text part
+ * @return this builder
+ */
+ public Builder textBody(String textBody) {
+ this.textBody = textBody;
+ return this;
+ }
+
+ /**
+ * Sets the RFC 3339 send time, which arms the campaign as scheduled.
+ *
+ * @param scheduledAt the RFC 3339 send time, which arms the campaign as scheduled
+ * @return this builder
+ */
+ public Builder scheduledAt(String scheduledAt) {
+ this.scheduledAt = scheduledAt;
+ return this;
+ }
+
+ /**
+ * Sets whether to send on creation, overriding the schedule.
+ *
+ * @param sendNow whether to send on creation, overriding the schedule
+ * @return this builder
+ */
+ public Builder sendNow(Boolean sendNow) {
+ this.sendNow = sendNow;
+ return this;
+ }
+
+ /**
+ * Builds the request.
+ *
+ * @return the immutable request
+ */
+ public DraftCampaignRequest build() {
+ return new DraftCampaignRequest(this);
+ }
+ }
+}
diff --git a/src/main/java/com/camelmailer/campaigns/SendCampaignRequest.java b/src/main/java/com/camelmailer/campaigns/SendCampaignRequest.java
new file mode 100644
index 0000000..bf92966
--- /dev/null
+++ b/src/main/java/com/camelmailer/campaigns/SendCampaignRequest.java
@@ -0,0 +1,153 @@
+package com.camelmailer.campaigns;
+
+/**
+ * Fields for {@link Campaigns#createAndSend}.
+ *
+ * There is no schedule here: the send starts before the call returns.
+ */
+public final class SendCampaignRequest {
+
+ private final String name;
+ private final String from;
+ private final String subject;
+ private final String htmlBody;
+ private final String textBody;
+
+ private SendCampaignRequest(Builder builder) {
+ this.name = builder.name;
+ this.from = builder.from;
+ this.subject = builder.subject;
+ this.htmlBody = builder.htmlBody;
+ this.textBody = builder.textBody;
+ }
+
+ /**
+ * Creates a new builder.
+ *
+ * @return a fresh builder
+ */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /**
+ * Returns the display name.
+ *
+ * @return the display name, or {@code null} when unset
+ */
+ public String getName() {
+ return name;
+ }
+
+ /**
+ * Returns the bare sender address.
+ *
+ * @return the bare sender address, or {@code null} when unset
+ */
+ public String getFrom() {
+ return from;
+ }
+
+ /**
+ * Returns the message subject.
+ *
+ * @return the message subject, or {@code null} when unset
+ */
+ public String getSubject() {
+ return subject;
+ }
+
+ /**
+ * Returns the HTML part.
+ *
+ * @return the HTML part, or {@code null} when unset
+ */
+ public String getHtmlBody() {
+ return htmlBody;
+ }
+
+ /**
+ * Returns the plain-text part.
+ *
+ * @return the plain-text part, or {@code null} when unset
+ */
+ public String getTextBody() {
+ return textBody;
+ }
+
+ /** Builder for {@link SendCampaignRequest}. */
+ public static final class Builder {
+
+ private String name;
+ private String from;
+ private String subject;
+ private String htmlBody;
+ private String textBody;
+
+ private Builder() {}
+
+ /**
+ * Sets the display name (required).
+ *
+ * @param name the display name
+ * @return this builder
+ */
+ public Builder name(String name) {
+ this.name = name;
+ return this;
+ }
+
+ /**
+ * Sets the bare sender address.
+ *
+ * @param from the bare sender address
+ * @return this builder
+ */
+ public Builder from(String from) {
+ this.from = from;
+ return this;
+ }
+
+ /**
+ * Sets the message subject.
+ *
+ * @param subject the message subject
+ * @return this builder
+ */
+ public Builder subject(String subject) {
+ this.subject = subject;
+ return this;
+ }
+
+ /**
+ * Sets the HTML part.
+ *
+ * @param htmlBody the HTML part
+ * @return this builder
+ */
+ public Builder htmlBody(String htmlBody) {
+ this.htmlBody = htmlBody;
+ return this;
+ }
+
+ /**
+ * Sets the plain-text part.
+ *
+ * @param textBody the plain-text part
+ * @return this builder
+ */
+ public Builder textBody(String textBody) {
+ this.textBody = textBody;
+ return this;
+ }
+
+ /**
+ * Builds the request.
+ *
+ * @return the immutable request
+ */
+ public SendCampaignRequest build() {
+ return new SendCampaignRequest(this);
+ }
+ }
+}
diff --git a/src/main/java/com/camelmailer/campaigns/UpdateCampaignRequest.java b/src/main/java/com/camelmailer/campaigns/UpdateCampaignRequest.java
new file mode 100644
index 0000000..37a5173
--- /dev/null
+++ b/src/main/java/com/camelmailer/campaigns/UpdateCampaignRequest.java
@@ -0,0 +1,208 @@
+package com.camelmailer.campaigns;
+
+/**
+ * Fields for {@link Campaigns#update}. Unset fields are left unchanged.
+ *
+ * The schedule is three-valued, which is why it has two builder methods: touching neither keeps
+ * the current schedule, {@code scheduledAt} moves a draft to {@code scheduled}, and {@code
+ * clearSchedule} sends an explicit {@code null}, which drops the campaign back to {@code draft}. An
+ * omitted field and a {@code null} mean different things to the API.
+ */
+public final class UpdateCampaignRequest {
+
+ private final String name;
+ private final String from;
+ private final String subject;
+ private final String htmlBody;
+ private final String textBody;
+ private final String scheduledAt;
+ private final boolean clearSchedule;
+
+ private UpdateCampaignRequest(Builder builder) {
+ this.name = builder.name;
+ this.from = builder.from;
+ this.subject = builder.subject;
+ this.htmlBody = builder.htmlBody;
+ this.textBody = builder.textBody;
+ this.scheduledAt = builder.scheduledAt;
+ this.clearSchedule = builder.clearSchedule;
+ }
+
+ /**
+ * Creates a new builder.
+ *
+ * @return a fresh builder
+ */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /**
+ * Returns the display name.
+ *
+ * @return the name, or {@code null} when unset
+ */
+ public String getName() {
+ return name;
+ }
+
+ /**
+ * Returns the sender address.
+ *
+ * @return the address, or {@code null} when unset
+ */
+ public String getFrom() {
+ return from;
+ }
+
+ /**
+ * Returns the subject.
+ *
+ * @return the subject, or {@code null} when unset
+ */
+ public String getSubject() {
+ return subject;
+ }
+
+ /**
+ * Returns the HTML part.
+ *
+ * @return the HTML body, or {@code null} when unset
+ */
+ public String getHtmlBody() {
+ return htmlBody;
+ }
+
+ /**
+ * Returns the plain-text part.
+ *
+ * @return the text body, or {@code null} when unset
+ */
+ public String getTextBody() {
+ return textBody;
+ }
+
+ /**
+ * Returns the schedule.
+ *
+ * @return the RFC 3339 send time, or {@code null} when unset or cleared
+ */
+ public String getScheduledAt() {
+ return scheduledAt;
+ }
+
+ /**
+ * Returns whether the update clears the schedule.
+ *
+ * {@link Campaigns#update} turns this into an explicit {@code null} in the body; an omitted
+ * field would leave the schedule standing.
+ *
+ * @return {@code true} when the schedule should be cleared
+ */
+ public boolean isClearSchedule() {
+ return clearSchedule;
+ }
+
+ /** Builder for {@link UpdateCampaignRequest}. */
+ public static final class Builder {
+
+ private String name;
+ private String from;
+ private String subject;
+ private String htmlBody;
+ private String textBody;
+ private String scheduledAt;
+ private boolean clearSchedule;
+
+ private Builder() {}
+
+ /**
+ * Sets the display name.
+ *
+ * @param name the name
+ * @return this builder
+ */
+ public Builder name(String name) {
+ this.name = name;
+ return this;
+ }
+
+ /**
+ * Sets the sender address.
+ *
+ * @param from the address
+ * @return this builder
+ */
+ public Builder from(String from) {
+ this.from = from;
+ return this;
+ }
+
+ /**
+ * Sets the subject.
+ *
+ * @param subject the subject
+ * @return this builder
+ */
+ public Builder subject(String subject) {
+ this.subject = subject;
+ return this;
+ }
+
+ /**
+ * Sets the HTML part.
+ *
+ * @param htmlBody the HTML body
+ * @return this builder
+ */
+ public Builder htmlBody(String htmlBody) {
+ this.htmlBody = htmlBody;
+ return this;
+ }
+
+ /**
+ * Sets the plain-text part.
+ *
+ * @param textBody the text body
+ * @return this builder
+ */
+ public Builder textBody(String textBody) {
+ this.textBody = textBody;
+ return this;
+ }
+
+ /**
+ * Schedules the campaign, moving a draft to {@code scheduled}.
+ *
+ * @param scheduledAt RFC 3339 send time
+ * @return this builder
+ */
+ public Builder scheduledAt(String scheduledAt) {
+ this.scheduledAt = scheduledAt;
+ this.clearSchedule = false;
+ return this;
+ }
+
+ /**
+ * Clears the schedule, dropping the campaign back to {@code draft}.
+ *
+ * This sends an explicit {@code null}; omitting the field would leave the schedule standing.
+ *
+ * @return this builder
+ */
+ public Builder clearSchedule() {
+ this.scheduledAt = null;
+ this.clearSchedule = true;
+ return this;
+ }
+
+ /**
+ * Builds the request.
+ *
+ * @return the immutable request
+ */
+ public UpdateCampaignRequest build() {
+ return new UpdateCampaignRequest(this);
+ }
+ }
+}
diff --git a/src/main/java/com/camelmailer/emails/Emails.java b/src/main/java/com/camelmailer/emails/Emails.java
index ab29f86..44a6efd 100644
--- a/src/main/java/com/camelmailer/emails/Emails.java
+++ b/src/main/java/com/camelmailer/emails/Emails.java
@@ -32,7 +32,39 @@ public Emails(ApiClient client) {
* @return the queue result
*/
public SendResult send(SendEmailRequest request) {
- return client.convert(client.post(BASE, request), SendResult.class);
+ return send(request, null);
+ }
+
+ /**
+ * Sends an email with an idempotency key.
+ *
+ * The same key with the same body returns the original result instead of queuing a second
+ * copy; the same key with a different body is refused with {@code InvalidIdempotentRequest} (HTTP
+ * 409) rather than silently ignored. Keys are scoped to the server and a completed result is kept
+ * for 24 hours.
+ *
+ * @param request the send parameters
+ * @param idempotencyKey the key, or {@code null} to send none
+ * @return the queue result
+ */
+ public SendResult send(SendEmailRequest request, String idempotencyKey) {
+ return client.convert(client.post(BASE, request, idempotencyKey), SendResult.class);
+ }
+
+ /**
+ * Sends the same content to every subscriber of a broadcast stream.
+ *
+ * The result counts what was queued against what was skipped: recipients past the per-request
+ * cap of 1000 are skipped rather than queued, so a larger audience wants a campaign.
+ *
+ * @param permalink the broadcast stream permalink
+ * @param request the content; give either a subject with a body, or a template
+ * @return how the broadcast was split
+ */
+ public StreamSendResult sendToStream(String permalink, SendEmailRequest request) {
+ return client.convert(
+ client.post("/api/v2/server/streams/" + permalink + "/send", request),
+ StreamSendResult.class);
}
/**
@@ -43,7 +75,18 @@ public SendResult send(SendEmailRequest request) {
* @return one result per request, in order
*/
public List The key travels as the {@code Idempotency-Key} header rather than in the body, because the
+ * body is what the server hashes to recognise the same request.
+ *
+ * @param path absolute API path
+ * @param body request body, serialized as JSON; {@code null} sends an empty JSON object
+ * @param idempotencyKey the key, or {@code null} to send none
+ * @return the {@code data} node of the success envelope
+ */
+ public JsonNode post(String path, Object body, String idempotencyKey) {
+ HttpRequest.Builder builder = request(path, Map.of());
+ if (idempotencyKey != null && !idempotencyKey.isEmpty()) {
+ builder = builder.header("Idempotency-Key", idempotencyKey);
+ }
+ return execute(builder.POST(jsonBody(body)).build());
+ }
+
+ /**
+ * Performs a DELETE request.
+ *
+ * @param path absolute API path
+ * @return the {@code data} node of the success envelope
+ */
+ public JsonNode delete(String path) {
+ return execute(request(path, Map.of()).DELETE().build());
}
/**
@@ -130,6 +163,18 @@ public Needed where a field has to reach the API as an explicit {@code null}: the mapper drops null
+ * properties, but a {@code NullNode} placed here survives.
+ *
+ * @return an empty object node
+ */
+ public ObjectNode newObject() {
+ return MAPPER.createObjectNode();
+ }
+
private HttpRequest.Builder request(String path, Map Covers mail arriving through an inbound route as well as outbound mail the spam filter put on
+ * hold, which is why a message here can be either retried or released past the hold.
+ *
+ * Obtain via {@link com.camelmailer.CamelMailer#inbound()}.
+ */
+public final class Inbound {
+
+ private static final String BASE = "/api/v2/server/inbound";
+
+ private final ApiClient client;
+
+ /**
+ * Creates the service.
+ *
+ * @param client the internal API client
+ */
+ public Inbound(ApiClient client) {
+ this.client = client;
+ }
+
+ /**
+ * Lists inbound and held messages, newest first.
+ *
+ * @return the first page, unfiltered
+ */
+ public InboundList list() {
+ return client.convert(client.get(BASE, Map.of()), InboundList.class);
+ }
+
+ /**
+ * Lists inbound and held messages with filters.
+ *
+ * @param options the filters
+ * @return the matching page
+ */
+ public InboundList list(ListInboundOptions options) {
+ return client.convert(client.get(BASE, options.toQuery()), InboundList.class);
+ }
+
+ /**
+ * Fetches one inbound message.
+ *
+ * @param id the message id
+ * @return the message
+ */
+ public Email get(long id) {
+ return client.convert(client.get(BASE + "/" + id).path("message"), Email.class);
+ }
+
+ /**
+ * Puts a message back on the delivery queue, for instance after fixing the route it should have
+ * matched.
+ *
+ * @param id the message id
+ * @return whether it was queued
+ */
+ public RequeueResult retry(long id) {
+ return client.convert(client.post(BASE + "/" + id + "/retry", null), RequeueResult.class);
+ }
+
+ /**
+ * Releases a held message past the hold and delivers it.
+ *
+ * @param id the message id
+ * @return whether it was queued
+ */
+ public RequeueResult bypass(long id) {
+ return client.convert(client.post(BASE + "/" + id + "/bypass", null), RequeueResult.class);
+ }
+}
diff --git a/src/main/java/com/camelmailer/inbound/InboundList.java b/src/main/java/com/camelmailer/inbound/InboundList.java
new file mode 100644
index 0000000..cf9da0b
--- /dev/null
+++ b/src/main/java/com/camelmailer/inbound/InboundList.java
@@ -0,0 +1,13 @@
+package com.camelmailer.inbound;
+
+import com.camelmailer.common.Pagination;
+import com.camelmailer.emails.Email;
+import java.util.List;
+
+/**
+ * One page of inbound and held messages.
+ *
+ * @param inbound the page of messages; the API names this key {@code inbound}, not {@code messages}
+ * @param pagination the page window
+ */
+public record InboundList(List {@code htmlWrapper} is required when creating, and has to embed the body with A layout wraps every template that uses it, so header, footer and styling live in one place
+ * instead of in each template.
+ *
+ * Obtain via {@link com.camelmailer.CamelMailer#layouts()}.
+ */
+public final class Layouts {
+
+ private static final String BASE = "/api/v2/server/layouts";
+
+ private final ApiClient client;
+
+ /**
+ * Creates the service.
+ *
+ * @param client the internal API client
+ */
+ public Layouts(ApiClient client) {
+ this.client = client;
+ }
+
+ /**
+ * Lists all layouts of the server.
+ *
+ * @return the layouts
+ */
+ public List {@code htmlWrapper} has to embed the body with Useful when a send did not arrive and the question is whether the request ever reached the
+ * API, and with what answer.
+ *
+ * Obtain via {@link com.camelmailer.CamelMailer#logs()}.
+ */
+public final class Logs {
+
+ private final ApiClient client;
+
+ /**
+ * Creates the service.
+ *
+ * @param client the internal API client
+ */
+ public Logs(ApiClient client) {
+ this.client = client;
+ }
+
+ /**
+ * Lists logged API requests, newest first.
+ *
+ * @return the first page
+ */
+ public LogList list() {
+ return list(null, null);
+ }
+
+ /**
+ * Lists logged API requests with paging.
+ *
+ * @param page 1-based page number, or {@code null} for the first
+ * @param perPage page size (capped at 100), or {@code null} for the default
+ * @return the matching page
+ */
+ public LogList list(Integer page, Integer perPage) {
+ Map Blanks and duplicates within the request are skipped, so {@code added} can be lower than the
+ * number of addresses passed.
+ *
+ * @param added subscriptions written
+ * @param total the stream's subscriber count after the import
+ */
+public record ImportResult(long added, long total) {}
diff --git a/src/main/java/com/camelmailer/subscribers/Subscriber.java b/src/main/java/com/camelmailer/subscribers/Subscriber.java
new file mode 100644
index 0000000..cd7bab0
--- /dev/null
+++ b/src/main/java/com/camelmailer/subscribers/Subscriber.java
@@ -0,0 +1,12 @@
+package com.camelmailer.subscribers;
+
+/**
+ * One address on a broadcast stream.
+ *
+ * @param id numeric subscriber id
+ * @param address the email address
+ * @param name optional display name
+ * @param status {@code subscribed} or {@code unsubscribed}
+ * @param createdAt when the subscription row was created
+ */
+public record Subscriber(long id, String address, String name, String status, String createdAt) {}
diff --git a/src/main/java/com/camelmailer/subscribers/SubscriberRequest.java b/src/main/java/com/camelmailer/subscribers/SubscriberRequest.java
new file mode 100644
index 0000000..d1175f6
--- /dev/null
+++ b/src/main/java/com/camelmailer/subscribers/SubscriberRequest.java
@@ -0,0 +1,107 @@
+package com.camelmailer.subscribers;
+
+/**
+ * Fields for {@link Subscribers#add}.
+ *
+ * Upserts by address, so calling it twice is safe.
+ */
+public final class SubscriberRequest {
+
+ private final String address;
+ private final String name;
+ private final String status;
+
+ private SubscriberRequest(Builder builder) {
+ this.address = builder.address;
+ this.name = builder.name;
+ this.status = builder.status;
+ }
+
+ /**
+ * Creates a new builder.
+ *
+ * @return a fresh builder
+ */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /**
+ * Returns the email address.
+ *
+ * @return the email address, or {@code null} when unset
+ */
+ public String getAddress() {
+ return address;
+ }
+
+ /**
+ * Returns the display name.
+ *
+ * @return the display name, or {@code null} when unset
+ */
+ public String getName() {
+ return name;
+ }
+
+ /**
+ * Returns {@code subscribed} (default) or {@code unsubscribed}.
+ *
+ * @return {@code subscribed} (default) or {@code unsubscribed}, or {@code null} when unset
+ */
+ public String getStatus() {
+ return status;
+ }
+
+ /** Builder for {@link SubscriberRequest}. */
+ public static final class Builder {
+
+ private String address;
+ private String name;
+ private String status;
+
+ private Builder() {}
+
+ /**
+ * Sets the email address (required).
+ *
+ * @param address the email address
+ * @return this builder
+ */
+ public Builder address(String address) {
+ this.address = address;
+ return this;
+ }
+
+ /**
+ * Sets the display name.
+ *
+ * @param name the display name
+ * @return this builder
+ */
+ public Builder name(String name) {
+ this.name = name;
+ return this;
+ }
+
+ /**
+ * Sets {@code subscribed} (default) or {@code unsubscribed}.
+ *
+ * @param status {@code subscribed} (default) or {@code unsubscribed}
+ * @return this builder
+ */
+ public Builder status(String status) {
+ this.status = status;
+ return this;
+ }
+
+ /**
+ * Builds the request.
+ *
+ * @return the immutable request
+ */
+ public SubscriberRequest build() {
+ return new SubscriberRequest(this);
+ }
+ }
+}
diff --git a/src/main/java/com/camelmailer/subscribers/Subscribers.java b/src/main/java/com/camelmailer/subscribers/Subscribers.java
new file mode 100644
index 0000000..a38773d
--- /dev/null
+++ b/src/main/java/com/camelmailer/subscribers/Subscribers.java
@@ -0,0 +1,107 @@
+package com.camelmailer.subscribers;
+
+import com.camelmailer.http.ApiClient;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+
+/**
+ * Opt-in subscribers of a broadcast stream: {@code /api/v2/server/streams/{permalink}/subscribers}.
+ *
+ * A broadcast send to an address that is not subscribed is refused, so this list is the
+ * audience.
+ *
+ * Obtain via {@link com.camelmailer.CamelMailer#subscribers()}.
+ */
+public final class Subscribers {
+
+ private final ApiClient client;
+
+ /**
+ * Creates the service.
+ *
+ * @param client the internal API client
+ */
+ public Subscribers(ApiClient client) {
+ this.client = client;
+ }
+
+ /**
+ * Lists the stream's subscribers, subscribed and unsubscribed alike.
+ *
+ * @param permalink the stream permalink
+ * @return the subscribers
+ */
+ public List Writes a stream-scoped suppression and flips the subscription to {@code unsubscribed}.
+ * Idempotent, so a feedback loop can replay it safely.
+ *
+ * @param permalink the stream permalink
+ * @param address the complaining address
+ * @return the updated subscriber
+ */
+ public Subscriber complaint(String permalink, String address) {
+ return client.convert(
+ client
+ .post(base(permalink) + "/" + encode(address) + "/complaint", null)
+ .path("subscriber"),
+ Subscriber.class);
+ }
+
+ /**
+ * Removes a subscriber from the stream entirely.
+ *
+ * @param permalink the stream permalink
+ * @param address the address to remove
+ * @return whether the row was removed
+ */
+ public boolean remove(String permalink, String address) {
+ return client.delete(base(permalink) + "/" + encode(address)).path("deleted").asBoolean();
+ }
+
+ private static String base(String permalink) {
+ return "/api/v2/server/streams/" + permalink + "/subscribers";
+ }
+
+ /**
+ * Percent-encodes an address for a path segment.
+ *
+ * {@link URLEncoder} is form encoding, which turns a space into {@code +} and leaves a literal
+ * {@code +} alone; in a path a bare plus is ambiguous, so it is escaped explicitly.
+ */
+ private static String encode(String address) {
+ return URLEncoder.encode(address, StandardCharsets.UTF_8).replace("+", "%2B");
+ }
+}
diff --git a/src/test/java/com/camelmailer/CampaignsTest.java b/src/test/java/com/camelmailer/CampaignsTest.java
new file mode 100644
index 0000000..21bff71
--- /dev/null
+++ b/src/test/java/com/camelmailer/CampaignsTest.java
@@ -0,0 +1,221 @@
+package com.camelmailer;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import com.camelmailer.campaigns.Campaign;
+import com.camelmailer.campaigns.CampaignDetail;
+import com.camelmailer.campaigns.DraftCampaignRequest;
+import com.camelmailer.campaigns.SendCampaignRequest;
+import com.camelmailer.campaigns.UpdateCampaignRequest;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+class CampaignsTest {
+
+ private static final String CAMPAIGN =
+ "{\"id\":7,\"name\":\"September\",\"subject\":\"What shipped\",\"from\":\"news@acme.com\","
+ + "\"status\":\"draft\",\"total\":120,\"sent\":0,\"stream_id\":3,"
+ + "\"stream\":{\"permalink\":\"product-news\",\"name\":\"Product news\"},"
+ + "\"scheduled_at\":null,\"created_at\":\"2026-09-01T10:00:00Z\",\"completed_at\":null}";
+
+ @Test
+ void listParsesCampaignsWithTheirStream() {
+ try (MockServer server = new MockServer()) {
+ server.enqueueData("{\"campaigns\":[" + CAMPAIGN + "]}");
+ List{@code
+ * ListInboundOptions options = ListInboundOptions.builder().status("held").perPage(50).build();
+ * }
+ */
+public final class ListInboundOptions {
+
+ private final String status;
+ private final String stream;
+ private final String query;
+ private final Integer page;
+ private final Integer perPage;
+
+ private ListInboundOptions(Builder builder) {
+ this.status = builder.status;
+ this.stream = builder.stream;
+ this.query = builder.query;
+ this.page = builder.page;
+ this.perPage = builder.perPage;
+ }
+
+ /**
+ * Creates a new builder.
+ *
+ * @return a fresh builder
+ */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /**
+ * Renders the filters as query parameters.
+ *
+ * @return the parameters; unset filters are omitted
+ */
+ public Map{{{ content }}}
+ * @param textWrapper wrapper for the plain-text body, or {@code null} when the layout has none
+ */
+public record Layout(
+ long id, String uuid, String name, String permalink, String htmlWrapper, String textWrapper) {}
diff --git a/src/main/java/com/camelmailer/layouts/LayoutRequest.java b/src/main/java/com/camelmailer/layouts/LayoutRequest.java
new file mode 100644
index 0000000..bb3104e
--- /dev/null
+++ b/src/main/java/com/camelmailer/layouts/LayoutRequest.java
@@ -0,0 +1,131 @@
+package com.camelmailer.layouts;
+
+/**
+ * Fields for creating or updating a template layout.
+ *
+ *
+ * {{{ content }}}; anything else is refused with {@code ValidationError}.
+ */
+public final class LayoutRequest {
+
+ private final String name;
+ private final String permalink;
+ private final String htmlWrapper;
+ private final String textWrapper;
+
+ private LayoutRequest(Builder builder) {
+ this.name = builder.name;
+ this.permalink = builder.permalink;
+ this.htmlWrapper = builder.htmlWrapper;
+ this.textWrapper = builder.textWrapper;
+ }
+
+ /**
+ * Creates a new builder.
+ *
+ * @return a fresh builder
+ */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /**
+ * Returns the display name.
+ *
+ * @return the display name, or {@code null} when unset
+ */
+ public String getName() {
+ return name;
+ }
+
+ /**
+ * Returns the URL-safe identifier, derived from the name when unset.
+ *
+ * @return the URL-safe identifier, derived from the name when unset, or {@code null} when unset
+ */
+ public String getPermalink() {
+ return permalink;
+ }
+
+ /**
+ * Returns the wrapper for the HTML body.
+ *
+ * @return the wrapper for the HTML body, or {@code null} when unset
+ */
+ public String getHtmlWrapper() {
+ return htmlWrapper;
+ }
+
+ /**
+ * Returns the wrapper for the plain-text body.
+ *
+ * @return the wrapper for the plain-text body, or {@code null} when unset
+ */
+ public String getTextWrapper() {
+ return textWrapper;
+ }
+
+ /** Builder for {@link LayoutRequest}. */
+ public static final class Builder {
+
+ private String name;
+ private String permalink;
+ private String htmlWrapper;
+ private String textWrapper;
+
+ private Builder() {}
+
+ /**
+ * Sets the display name.
+ *
+ * @param name the display name
+ * @return this builder
+ */
+ public Builder name(String name) {
+ this.name = name;
+ return this;
+ }
+
+ /**
+ * Sets the URL-safe identifier, derived from the name when unset.
+ *
+ * @param permalink the URL-safe identifier, derived from the name when unset
+ * @return this builder
+ */
+ public Builder permalink(String permalink) {
+ this.permalink = permalink;
+ return this;
+ }
+
+ /**
+ * Sets the wrapper for the HTML body.
+ *
+ * @param htmlWrapper the wrapper for the HTML body
+ * @return this builder
+ */
+ public Builder htmlWrapper(String htmlWrapper) {
+ this.htmlWrapper = htmlWrapper;
+ return this;
+ }
+
+ /**
+ * Sets the wrapper for the plain-text body.
+ *
+ * @param textWrapper the wrapper for the plain-text body
+ * @return this builder
+ */
+ public Builder textWrapper(String textWrapper) {
+ this.textWrapper = textWrapper;
+ return this;
+ }
+
+ /**
+ * Builds the request.
+ *
+ * @return the immutable request
+ */
+ public LayoutRequest build() {
+ return new LayoutRequest(this);
+ }
+ }
+}
diff --git a/src/main/java/com/camelmailer/layouts/Layouts.java b/src/main/java/com/camelmailer/layouts/Layouts.java
new file mode 100644
index 0000000..68cfc90
--- /dev/null
+++ b/src/main/java/com/camelmailer/layouts/Layouts.java
@@ -0,0 +1,98 @@
+package com.camelmailer.layouts;
+
+import com.camelmailer.http.ApiClient;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import java.util.List;
+
+/**
+ * Template layouts: {@code /api/v2/server/layouts}.
+ *
+ * {{{ content }}}; anything else
+ * is refused with {@code ValidationError}.
+ *
+ * @param request the layout fields
+ * @return the created layout
+ */
+ public Layout create(LayoutRequest request) {
+ return client.convert(client.post(BASE, request).path("layout"), Layout.class);
+ }
+
+ /**
+ * Fetches a layout by permalink.
+ *
+ * @param permalink the layout permalink
+ * @return the layout
+ */
+ public Layout get(String permalink) {
+ return client.convert(client.get(BASE + "/" + permalink).path("layout"), Layout.class);
+ }
+
+ /**
+ * Updates a layout; only the given fields change.
+ *
+ * @param permalink the layout permalink
+ * @param request the fields to change
+ * @return the updated layout
+ */
+ public Layout update(String permalink, LayoutRequest request) {
+ return client.convert(
+ client.patch(BASE + "/" + permalink, request).path("layout"), Layout.class);
+ }
+
+ /**
+ * Deletes a layout. Templates that referenced it fall back to no wrapper.
+ *
+ * @param permalink the layout permalink
+ * @return whether the layout was removed
+ */
+ public boolean delete(String permalink) {
+ return client.delete(BASE + "/" + permalink).path("deleted").asBoolean();
+ }
+
+ /**
+ * Uploads the layout's logo, given as a {@code data:image/png;base64,...} URL.
+ *
+ * @param permalink the layout permalink
+ * @param dataUrl the logo as a data URL
+ * @return the absolute URL to reference from the wrapper; it is served without authentication,
+ * because mail clients fetch it without a session
+ */
+ public String uploadLogo(String permalink, String dataUrl) {
+ ObjectNode body = client.newObject();
+ body.put("data_url", dataUrl);
+ // The endpoint answers with "url", not "logo_url".
+ return client.post(BASE + "/" + permalink + "/logo", body).path("url").asText();
+ }
+}
diff --git a/src/main/java/com/camelmailer/logs/ApiRequestLog.java b/src/main/java/com/camelmailer/logs/ApiRequestLog.java
new file mode 100644
index 0000000..1e958e3
--- /dev/null
+++ b/src/main/java/com/camelmailer/logs/ApiRequestLog.java
@@ -0,0 +1,21 @@
+package com.camelmailer.logs;
+
+/**
+ * One logged API request.
+ *
+ * @param id numeric log id
+ * @param method the HTTP method
+ * @param path the request path
+ * @param statusCode the status the API answered with
+ * @param durationMs how long the request took, in milliseconds
+ * @param userAgent the client's User-Agent header
+ * @param createdAt when the request arrived
+ */
+public record ApiRequestLog(
+ long id,
+ String method,
+ String path,
+ int statusCode,
+ long durationMs,
+ String userAgent,
+ String createdAt) {}
diff --git a/src/main/java/com/camelmailer/logs/LogList.java b/src/main/java/com/camelmailer/logs/LogList.java
new file mode 100644
index 0000000..f7a3e2f
--- /dev/null
+++ b/src/main/java/com/camelmailer/logs/LogList.java
@@ -0,0 +1,12 @@
+package com.camelmailer.logs;
+
+import com.camelmailer.common.Pagination;
+import java.util.List;
+
+/**
+ * One page of logged requests.
+ *
+ * @param requests the page of logged requests
+ * @param pagination the page window
+ */
+public record LogList(List