notifyhub

What is NotifyHub?

NotifyHub is a unified notification library for Java and Spring Boot. Instead of integrating each channel separately (Twilio SDK for SMS, JavaMail for email, webhook calls for Slack...), you use one fluent API for everything.

📦

Library

Add as a Maven/Gradle dependency. Spring Boot auto-configures everything. Just @Autowired NotifyHub and send.

🌐

REST API

Don't use Java? Run our Docker image and call HTTP endpoints from any language. Swagger UI included.

🤖

AI Ready

MCP Server with 33 tools. Let Claude, Cursor, or any AI assistant send notifications on your behalf.

No Code Required

Send notifications from Claude, Cursor, or any AI assistant. Just talk naturally — NotifyHub handles the rest.

1

Download

Get the NotifyHub MCP executable.
No Java, no dependencies.

2

Setup (3 min)

Run notifyhub-mcp --setup
The wizard configures everything.

3

Talk to AI

Open Claude and say:
"Send an email to [email protected]"

What you can say

"Send a Slack message to #general saying deployment is complete"

"Notify my team on Discord that the build failed"

"Email the client the project update"

"Send a Telegram message to the ops channel"

"Post on Twitter that v2.0 is live"

"Send an SMS to +1234567890 with the verification code"

Works with 10+ AI editors

Claude Desktop • Claude Code • Cursor • Windsurf • VS Code + Copilot • Cline • Roo Code • Continue.dev • Amazon Q • and more

23 Channels. Zero Friction.

Every channel uses the same API. Most use zero external SDKs — just the JDK HttpClient. Add only the channels you need.

Email

SMTP (Gmail, SES, Outlook, any). HTML templates, attachments, TLS.

SMS

Twilio. Send text messages worldwide with delivery status.

WhatsApp

Twilio or WhatsApp Cloud API. Media attachments supported.

Slack

Incoming Webhooks. Named channels, no SDK needed.

Telegram

Bot API. Send to any chat ID or named alias.

Discord

Webhooks. Custom username, avatar, named servers.

Microsoft Teams

Incoming Webhooks. MessageCard format.

Google Chat

Webhooks. Send to any Google Chat space.

Firebase Push

FCM. Mobile push notifications with title and body.

WebSocket

JDK WebSocket with auto-reconnect. Real-time.

Generic Webhook

Any HTTP endpoint. PagerDuty, Datadog, custom APIs.

Twitter / X

API v2. Post tweets with OAuth 1.0a. No SDK needed.

LinkedIn

REST API. Publish posts with OAuth 2.0 Bearer token.

Notion

API. Create pages in any database. Integration Token.

Twitch

Helix API. Chat messages + polls. OAuth auto-refresh.

YouTube

Data API v3. Live chat messages. OAuth auto-refresh.

Instagram

Meta Graph API. DMs and feed posts. No SDK needed.

SendGrid

Email delivery tracking — opened, clicked, bounced, spam complaints.

TikTok Shop

Shop notifications with HMAC-SHA256 authentication.

Facebook

Page posts & Messenger DMs via Graph API.

AWS SNS

Topics, push endpoints, and SMS via Amazon SNS.

Mailgun

Transactional email via Mailgun REST API.

PagerDuty

Trigger incidents via Events API v2.

Custom

Implement one interface. Your channel, your rules.

Everything You Need

NotifyHub isn't just a message sender. It's a complete notification infrastructure with retry, tracking, templates, scheduling, and more.

⚙ Fluent API

Builder pattern with chaining. .to().via().fallback().template().send() — readable and type-safe.

🔄 Fallback Chains

If WhatsApp fails, try SMS. If SMS fails, try Email. Automatic failover with no extra code.

📋 Mustache Templates

HTML for email, plain text for chat. Template versioning for A/B tests. i18n with locale fallback.

👥 Batch Send

toAll(recipients) and toAllNotifiable(users). Send to thousands with failure isolation.

⏳ Scheduling

Schedule, list, and cancel notifications. Use relative delays or absolute timestamps with timezone support.

🔁 Retry & DLQ

Exponential or fixed backoff. Failed after all retries? Goes to Dead Letter Queue for manual reprocessing.

📈 Rate Limiting

Token bucket per channel. Configurable limits. URGENT priority bypasses the limiter.

🔍 Delivery Tracking

Every send returns a DeliveryReceipt. Email tracking via SendGrid: opened, clicked, bounced, spam complaints.

🔒 Deduplication

Content-hash or explicit key. Same message won't be sent twice within the TTL window.

⚡ Async

sendAsync() and sendAllAsync() return CompletableFuture. Non-blocking sends.

👤 Named Recipients

Define aliases like "alerts", "devops". Send to a name, resolve to webhook URL or chat ID.

📦 Message Queues

RabbitMQ and Kafka modules. Enqueue notifications for async, distributed processing.

👁 OpenTelemetry

Auto-configured tracing via Micrometer Observation API. Export spans to Jaeger, Tempo, or any OTLP collector.

🛡 Circuit Breaker

Per-channel circuit breaker with sliding failure window. Prevents cascading failures with CLOSED → OPEN → HALF_OPEN states.

📋 Orchestration

Multi-step escalation: first(EMAIL).ifNoOpen(24h).then(PUSH). Promote through channels if users don't engage.

🔬 A/B Testing

Built-in deterministic variant selection via SHA-256 hashing. Split traffic across template variants with weighted percentages.

🔧 TestNotifyHub

Test utility with capturing channels. Assert on sent notifications without mocking. Zero test infrastructure needed.

For Developers

One fluent Java API. 23 channels. 3 lines of code. Spring Boot auto-configured.

Java — That's it. Really.

notify.to("[email protected]")
    .via(EMAIL)
    .fallback(SLACK)
    .subject("Order Confirmed")
    .content("Your order #123 has shipped!")
    .send();

Developer Docs Maven Central

See It In Action

A few lines of code. That's all it takes.

Send an email with fallback to SMS

Java

notify.to("[email protected]")
    .via(Channel.EMAIL)
    .fallback(Channel.SMS)
    .subject("Order Confirmed")
    .template("order-confirmed")
    .param("orderId", "ORD-2024")
    .send();

Send to multiple channels at once

Java

notify.to(user)
    .via(Channel.EMAIL)
    .via(Channel.SLACK)
    .via(Channel.DISCORD)
    .subject("Security Alert")
    .content("Login from a new device detected")
    .sendAll();

Batch send to thousands

Java

notify.toAll(List.of("[email protected]", "[email protected]", "[email protected]"))
    .via(Channel.EMAIL)
    .subject("System Maintenance")
    .template("maintenance-notice")
    .param("date", "2025-03-01")
    .send();

Schedule for later + track delivery

Java

DeliveryReceipt receipt = notify.to(user)
    .via(Channel.EMAIL)
    .subject("Reminder")
    .content("Don't forget your appointment!")
    .sendTracked();

receipt.getStatus();    // SENT
receipt.getId();        // uuid
receipt.getTimestamp(); // 2025-01-15T10:30:00Z

Quick Start

Add the dependency, configure your channels, and start sending.

1

Add the dependency

pom.xml

<dependency>
    <groupId>io.github.gabrielbbaldez</groupId>
    <artifactId>notify-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>
<!-- Add the channels you need -->
<dependency>
    <groupId>io.github.gabrielbbaldez</groupId>
    <artifactId>notify-email</artifactId>
    <version>1.0.0</version>
</dependency>

2

Configure in application.yml

application.yml

notify:
  channels:
    email:
      host: smtp.gmail.com
      port: 587
      username: ${GMAIL_USER}
      password: ${GMAIL_PASS}
      from: [email protected]
      tls: true
    slack:
      webhook-url: ${SLACK_WEBHOOK}
    discord:
      webhook-url: ${DISCORD_WEBHOOK}
  retry:
    max-attempts: 3
    strategy: exponential
  tracking:
    enabled: true

3

Send notifications

Java

@Autowired NotifyHub notify;

notify.to("[email protected]")
    .via(Channel.EMAIL)
    .fallback(Channel.SMS)
    .subject("Welcome!")
    .template("welcome")
    .param("name", "Gabriel")
    .send();

Docker

Don't use Java? No problem. Run NotifyHub as a REST API or MCP Server with Docker. Just set environment variables for the channels you want.

REST API gabrielbbal10/notifyhub-api

Full REST API with Swagger UI on port 8080. Send notifications via HTTP from Python, Node.js, Go, cURL, or any language.

Docker Hub Docs

Run it

docker run -d -p 8080:8080 \
  -e [email protected] \
  -e NOTIFY_CHANNELS_EMAIL_PASSWORD=your-app-password \
  -e [email protected] \
  -e NOTIFY_CHANNELS_DISCORD_WEBHOOK_URL="https://discord.com/..." \
  gabrielbbal10/notifyhub-api:latest

Call the API

# Send email
curl -X POST "localhost:8080/send/[email protected]&subject=Hi&body=Hello!"

# Send Discord
curl -X POST "localhost:8080/send/discord?message=Deploy done!"

# Swagger UI
open http://localhost:8080/swagger-ui.html

MCP Server gabrielbbal10/notifyhub-mcp

Model Context Protocol server with 33 tools for AI assistants. Connect to Claude Desktop, Claude Code, or Cursor.

Docker Hub Docs

claude_desktop_config.json

{
  "mcpServers": {
    "notify-hub": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "NOTIFY_CHANNELS_DISCORD_WEBHOOK_URL=...",
        "-e", "[email protected]",
        "-e", "NOTIFY_CHANNELS_EMAIL_PASSWORD=app-password",
        "-e", "[email protected]",
        "gabrielbbal10/notifyhub-mcp"
      ]
    }
  }
}

Environment Variables

Both Docker images use the same NOTIFY_CHANNELS_* variables. Only set the channels you need.

Email (SMTP)

• NOTIFY_CHANNELS_EMAIL_HOST smtp.gmail.com
• NOTIFY_CHANNELS_EMAIL_PORT 587
• NOTIFY_CHANNELS_EMAIL_USERNAME [email protected]
• NOTIFY_CHANNELS_EMAIL_PASSWORD app-password
• NOTIFY_CHANNELS_EMAIL_FROM [email protected]

Discord

• NOTIFY_CHANNELS_DISCORD_WEBHOOK_URL https://discord.com/...
• NOTIFY_CHANNELS_DISCORD_USERNAME NotifyHub

Slack

• NOTIFY_CHANNELS_SLACK_WEBHOOK_URL https://hooks.slack.com/...

Telegram

• NOTIFY_CHANNELS_TELEGRAM_BOT_TOKEN 123456:ABC...
• NOTIFY_CHANNELS_TELEGRAM_CHAT_ID 123456789

Teams

• NOTIFY_CHANNELS_TEAMS_WEBHOOK_URL https://outlook.office.com/...

SMS (Twilio)

• NOTIFY_CHANNELS_SMS_ACCOUNT_SID AC...
• NOTIFY_CHANNELS_SMS_AUTH_TOKEN token
• NOTIFY_CHANNELS_SMS_FROM_NUMBER +15551234567

Google Chat

• NOTIFY_CHANNELS_GOOGLE_CHAT_WEBHOOK_URL https://chat.googleapis.com/...

Built for AI

NotifyHub includes an MCP Server (Model Context Protocol) that exposes 33 tools. Connect it to Claude Desktop, Claude Code, Cursor, or any MCP-compatible AI client.

36 MCP Tools

send_email send_sms send_whatsapp send_slack send_telegram send_discord send_teams send_google_chat send_push send_twitter send_linkedin send_notion send_twitch send_youtube send_instagram send_tiktok_shop send_facebook send_aws_sns send_mailgun send_pagerduty send_notification send_multi_channel send_batch send_to_audience create_contact list_contacts create_audience list_audiences list_channels list_delivery_receipts list_dead_letters get_analytics check_email_status schedule_notification list_scheduled_notifications cancel_scheduled_notification

What you can say to your AI

"Send an email to [email protected] saying the deploy is complete"

"Create a VIP audience with tags 'premium' and 'active', then send them a promo email"

"Send an SMS to +5548999999999 with the verification code"

"Notify the team on Slack and Telegram that the build passed"

"Show me the delivery analytics — how many sent vs failed?"

"Schedule an email reminder for tomorrow at 9am"

"Check if the last email was opened or bounced"

Claude Code Skill

AI-powered development assistant — knows the entire NotifyHub API

NotifyHub ships a SKILL.md file (925 lines) that teaches AI coding assistants the full library API. Install it as a Claude Code plugin and your AI knows every channel config, fluent builder method, Spring Boot property, template pattern, retry policy, rate limit preset, and MCP tool — no need to search docs.

📚

Full API Reference 23 channels, fluent builder, all execution methods, Priority, DeliveryReceipt

⚙️

Every Config & Property Java builder + complete application.yml for all channels including OAuth refresh

🤖

33 MCP Tools Documented Send, batch, audience, contacts, analytics, scheduling, email tracking, DLQ — all tool signatures

🛠️

Patterns & Architecture Create new channels, custom templates, retry, rate limiting, thread safety

Install as Claude Code Plugin

# Copy SKILL.md to your Claude Code plugins directory
mkdir -p ~/.claude/plugins/notifyhub/skills/notifyhub
cp SKILL.md ~/.claude/plugins/notifyhub/skills/notifyhub/

Once installed, Claude Code automatically uses the skill whenever you work with NotifyHub — generating correct configs, writing channel implementations, debugging send failures, and more.

Message Queues

For high-throughput or distributed systems, enqueue notifications to RabbitMQ or Kafka. A consumer picks them up and sends via NotifyHub automatically.

RabbitMQ

notify-queue-rabbitmq

application.yml

notify.queue.rabbitmq:
  enabled: true
  queue-name: notifyhub-notifications
  exchange-name: notifyhub-exchange
  routing-key: notification

Apache Kafka

notify-queue-kafka

application.yml

notify.queue.kafka:
  enabled: true
  topic: notifyhub-notifications
  consumer:
    group-id: notifyhub-group

Admin Dashboard

Built-in web UI at /notify-admin with 8 pages. Dark/light theme toggle, responsive design, shared CSS architecture.

📈 Dashboard

Metric cards, recent activity feed, system status, channel overview.

📊 Analytics

Chart.js charts: volume, distribution, success rate, hourly heatmap.

🔍 Tracking

Every delivery receipt. Filter by channel, status, recipient.

🗑 Dead Letter Queue

Failed after all retries. Inspect error, remove from queue.

📡 Channels

All registered channels with health indicators and type info.

📝 Audit Log

Complete event history with type filter. Sent, failed, scheduled, cancelled.

👥 Audiences

Manage contacts and segments with tag-based filtering.

🔗 Status Webhook

HTTP callback config, recent deliveries, payload inspection.

28 Modules. Pick What You Need.

NotifyHub is modular. The core has zero Spring dependency. Add only the channels and features you use.

Module	What it does
notify-core	Fluent API, templates, retry, DLQ, rate limiting, tracking. Zero Spring dependency.
notify-spring-boot-starter	Auto-configures everything for Spring Boot. The main entry point.
notify-email	SMTP email with Jakarta Mail. HTML, attachments, TLS/SSL.
notify-sms	SMS + WhatsApp via Twilio or WhatsApp Cloud API.
notify-slack	Slack via Incoming Webhooks. No SDK.
notify-telegram	Telegram via Bot API. No SDK.
notify-discord	Discord via Webhooks. No SDK.
notify-teams	Microsoft Teams via Webhooks. No SDK.
notify-google-chat	Google Chat via Webhooks. No SDK.
notify-push-firebase	Firebase Cloud Messaging push notifications.
notify-webhook	Generic HTTP webhooks. Configurable payload templates.
notify-websocket	JDK WebSocket with auto-reconnect.
notify-twitter	Twitter/X via API v2 with OAuth 1.0a. No SDK.
notify-linkedin	LinkedIn via REST API with OAuth 2.0. No SDK.
notify-notion	Notion via API. Create pages in any database.
notify-twitch	Twitch via Helix API. Chat messages + polls.
notify-youtube	YouTube via Data API v3. Live chat messages.
notify-instagram	Instagram via Meta Graph API. DMs and feed posts.
notify-sendgrid	SendGrid email with delivery tracking (opened, clicked, bounced, spam).
notify-tiktok-shop	TikTok Shop API with HMAC-SHA256 authentication.
notify-facebook	Facebook Graph API. Page posts and Messenger DMs.
notify-aws-sns	Amazon SNS. Topics, push endpoints, and direct SMS.
notify-mailgun	Mailgun REST API. Transactional email with US/EU regions.
notify-pagerduty	PagerDuty Events API v2. Incident triggering with severity.
notify-tracker-jpa	JPA-backed delivery tracking. Persist receipts to any database.
notify-audit-jpa	JPA-backed audit logging. Persist events to any database.
notify-admin	Web dashboard for monitoring and DLQ management.
notify-mcp	MCP Server for AI assistants (36 tools).
notify-queue-rabbitmq	RabbitMQ producer/consumer for async notifications.
notify-queue-kafka	Apache Kafka producer/consumer for async notifications.