Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 23 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
115 changes: 114 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down Expand Up @@ -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("<html><body>{{{ content }}}</body></html>")
.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);
List<TagCount> tags = client.logs().tags();
```

### Stats and bounces

```java
Expand Down
2 changes: 1 addition & 1 deletion pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

<groupId>com.camelmailer</groupId>
<artifactId>camelmailer-java</artifactId>
<version>0.1.0</version>
<version>0.2.0</version>
<packaging>jar</packaging>

<name>camelmailer-java</name>
Expand Down
62 changes: 61 additions & 1 deletion src/main/java/com/camelmailer/CamelMailer.java
Original file line number Diff line number Diff line change
@@ -1,11 +1,16 @@
package com.camelmailer;

import com.camelmailer.bounces.Bounces;
import com.camelmailer.campaigns.Campaigns;
import com.camelmailer.dmarc.Dmarc;
import com.camelmailer.emails.Emails;
import com.camelmailer.http.ApiClient;
import com.camelmailer.inbound.Inbound;
import com.camelmailer.layouts.Layouts;
import com.camelmailer.logs.Logs;
import com.camelmailer.stats.Stats;
import com.camelmailer.streams.Streams;
import com.camelmailer.subscribers.Subscribers;
import com.camelmailer.templates.Templates;
import java.net.http.HttpClient;

Expand Down Expand Up @@ -47,6 +52,11 @@ public final class CamelMailer {
private final Stats stats;
private final Bounces bounces;
private final Dmarc dmarc;
private final Campaigns campaigns;
private final Subscribers subscribers;
private final Layouts layouts;
private final Inbound inbound;
private final Logs logs;

/**
* Creates a client for the CamelMailer cloud ({@value #DEFAULT_BASE_URL}).
Expand All @@ -70,6 +80,11 @@ private CamelMailer(Builder builder) {
this.stats = new Stats(api);
this.bounces = new Bounces(api);
this.dmarc = new Dmarc(api);
this.campaigns = new Campaigns(api);
this.subscribers = new Subscribers(api);
this.layouts = new Layouts(api);
this.inbound = new Inbound(api);
this.logs = new Logs(api);
}

/**
Expand Down Expand Up @@ -127,7 +142,52 @@ public Bounces bounces() {
}

/**
* DMARC compliance reporting.
* Broadcast campaigns.
*
* @return the campaigns service
*/
public Campaigns campaigns() {
return campaigns;
}

/**
* Opt-in subscribers of a broadcast stream.
*
* @return the subscribers service
*/
public Subscribers subscribers() {
return subscribers;
}

/**
* Template layouts.
*
* @return the layouts service
*/
public Layouts layouts() {
return layouts;
}

/**
* Inbound and held messages.
*
* @return the inbound service
*/
public Inbound inbound() {
return inbound;
}

/**
* The server's request log and tag index.
*
* @return the logs service
*/
public Logs logs() {
return logs;
}

/**
* DMARC monitoring.
*
* @return the DMARC service
*/
Expand Down
36 changes: 36 additions & 0 deletions src/main/java/com/camelmailer/campaigns/Campaign.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
package com.camelmailer.campaigns;

/**
* A broadcast campaign: content plus an audience.
*
* @param id numeric campaign id
* @param name display name
* @param subject message subject
* @param from sender address
* @param htmlBody HTML part
* @param textBody plain-text part
* @param status lifecycle state: {@code draft}, {@code scheduled}, {@code sending}, {@code sent},
* {@code failed} or {@code canceled}. Only draft and scheduled are editable.
* @param total recipient count snapshotted when the send begins
* @param sent recipients expanded into messages so far
* @param streamId id of the audience stream
* @param stream permalink and name of the audience stream
* @param scheduledAt send time of a scheduled campaign, or {@code null}
* @param createdAt when the campaign row was created
* @param completedAt when expansion finished ({@code sent} or {@code failed})
*/
public record Campaign(
long id,
String name,
String subject,
String from,
String htmlBody,
String textBody,
String status,
long total,
long sent,
long streamId,
CampaignStream stream,
String scheduledAt,
String createdAt,
String completedAt) {}
9 changes: 9 additions & 0 deletions src/main/java/com/camelmailer/campaigns/CampaignDetail.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
package com.camelmailer.campaigns;

/**
* A campaign together with its statistics.
*
* @param campaign the campaign itself
* @param stats its counters
*/
public record CampaignDetail(Campaign campaign, CampaignStats stats) {}
21 changes: 21 additions & 0 deletions src/main/java/com/camelmailer/campaigns/CampaignStats.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
package com.camelmailer.campaigns;

/**
* Per-campaign counters, attributed through the messages the campaign produced.
*
* @param total recipient count of the campaign
* @param sent messages created
* @param delivered messages delivered
* @param failed messages that failed
* @param opened messages opened at least once
* @param clicked messages with at least one click
* @param unsubscribed resulting unsubscribes
*/
public record CampaignStats(
long total,
long sent,
long delivered,
long failed,
long opened,
long clicked,
long unsubscribed) {}
9 changes: 9 additions & 0 deletions src/main/java/com/camelmailer/campaigns/CampaignStream.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
package com.camelmailer.campaigns;

/**
* The audience stream carried on every campaign, so a list needs no second lookup.
*
* @param permalink URL-safe identifier of the stream
* @param name display name of the stream
*/
public record CampaignStream(String permalink, String name) {}
Loading
Loading