Skip to main content

Notifications

client.notifications() is the core of the SDK — building requests, sending them, searching history, and reading delivery receipts.

Anatomy of a request​

NotificationRequest is built with a fluent builder. Each channel has a matching to* method that targets the recipient field the API expects for that channel:

ChanneladdChannel valueRecipient method
EmailChannelType.EMAIL.toEmail(address)
SMSChannelType.SMS.toPhone(number)
WebhookChannelType.WEBHOOK.toWebhook(url)
Push (device)ChannelType.PUSH.toPushToken(token)
Push (topic)ChannelType.PUSH.toPushTopic(topic)
In-appChannelType.IN_APP.toInApp(userId)

Two additional builder methods attach rich-media fields shared across channels: .withMediaUrl(imageUrl) and .withActionUrl(actionUrl).

Content can come from either inline fields or a template:

  • .subject(...) / .message(...) — inline content
  • .templateId(...) + .addVariable(key, value) — rendered from a saved template

.scheduleFor(timestamp) defers delivery to a future time instead of sending immediately.

build() throws if no channel was added via addChannel(...).

Multi-channel requests​

A single request can target more than one channel at once — call addChannel multiple times and set the recipient fields for each:

var request = NotificationRequest.builder()
        .addChannel(ChannelType.EMAIL)
        .addChannel(ChannelType.SMS)
        .toEmail("user@example.com")
        .toPhone("+15551234567")
        .subject("Order shipped")
        .message("Your order is on its way.")
        .build();

client.notifications().send(request);

Idempotent sends​

Pass your own idempotency key to safely retry a send without risking a duplicate delivery:

UUID idempotencyKey = UUID.randomUUID();
var response = client.notifications().sendWithIdempotency(request, idempotencyKey);

send(request) is equivalent to calling sendWithIdempotency(request, null).

Bulk sending​

var results = client.notifications().sendBulk(List.of(request1, request2, request3));

Scheduling and cancellation​

var request = NotificationRequest.builder()
        .addChannel(ChannelType.EMAIL)
        .toEmail("user@example.com")
        .subject("Reminder")
        .message("Your trial ends tomorrow.")
        .scheduleFor(Instant.now().plus(Duration.ofDays(1)))
        .build();

var response = client.notifications().send(request);

// Cancel before it fires, using the task id from the response
client.notifications().cancelSchedule(taskId);

Searching and reading history​

var receipts = client.notifications().search(ChannelType.EMAIL, "DELIVERED", 20, 0);
var one = client.notifications().get(notificationId);
var receiptDetail = client.notifications().getReceipts(notificationId);

search accepts null for channel and status to leave either filter unset.