{"id":44266989,"url":"https://github.com/fireflyframework/fireflyframework-notifications-sendgrid","last_synced_at":"2026-05-31T20:00:45.665Z","repository":{"id":336856858,"uuid":"1151407613","full_name":"fireflyframework/fireflyframework-notifications-sendgrid","owner":"fireflyframework","description":"SendGrid email delivery adapter for Firefly Notifications.","archived":false,"fork":false,"pushed_at":"2026-05-19T19:08:38.000Z","size":66,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-19T21:05:23.122Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fireflyframework.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-06T12:33:34.000Z","updated_at":"2026-05-19T19:09:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fireflyframework/fireflyframework-notifications-sendgrid","commit_stats":null,"previous_names":["fireflyframework/fireflyframework-notifications-sendgrid"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/fireflyframework/fireflyframework-notifications-sendgrid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireflyframework%2Ffireflyframework-notifications-sendgrid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireflyframework%2Ffireflyframework-notifications-sendgrid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireflyframework%2Ffireflyframework-notifications-sendgrid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireflyframework%2Ffireflyframework-notifications-sendgrid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fireflyframework","download_url":"https://codeload.github.com/fireflyframework/fireflyframework-notifications-sendgrid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireflyframework%2Ffireflyframework-notifications-sendgrid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33746513,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-10T18:25:43.158Z","updated_at":"2026-05-31T20:00:45.640Z","avatar_url":"https://github.com/fireflyframework.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Firefly Framework - Notifications SendGrid\n\n[![CI](https://github.com/fireflyframework/fireflyframework-notifications-sendgrid/actions/workflows/ci.yml/badge.svg)](https://github.com/fireflyframework/fireflyframework-notifications-sendgrid/actions/workflows/ci.yml)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Java](https://img.shields.io/badge/Java-21%2B-orange.svg)](https://openjdk.org)\n[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.x-green.svg)](https://spring.io/projects/spring-boot)\n\n\u003e SendGrid email delivery adapter for the Firefly Framework notifications abstraction — a reactive `EmailProvider` that sends transactional email (HTML/plain text, CC/BCC, attachments) through the SendGrid v3 Mail Send API.\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [How It Works](#how-it-works)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Overview\n\n`fireflyframework-notifications-sendgrid` is a pluggable **email provider adapter** for the Firefly Framework notifications subsystem. It implements the core\n`EmailProvider` SPI (`org.fireflyframework.notifications.interfaces.providers.email.v1.EmailProvider`) defined in\n[`fireflyframework-notifications-core`](https://github.com/fireflyframework/fireflyframework-notifications), backing it with [Twilio SendGrid](https://www.twilio.com/en-us/sendgrid/email-api) as the delivery channel.\n\nThe notifications core exposes a transport-agnostic `EmailService` facade; the actual wire delivery is delegated to whichever `EmailProvider` bean is present on the classpath. This module supplies that bean — `SendGridEmailProvider` — so application code keeps depending only on the core abstraction and never on the SendGrid SDK directly. Swapping SendGrid for another email backend (for example a Resend or SMTP adapter) is a dependency-and-configuration change, not a code change.\n\nThe adapter is **selected** by setting `firefly.notifications.email.provider=sendgrid`. When that property matches and the SendGrid SDK is on the classpath, the bundled Spring Boot auto-configuration wires a `SendGrid` client (from your API key) and the `SendGridEmailProvider` automatically — no manual `@Bean` declarations required. Because it builds on the blocking `sendgrid-java` SDK, the adapter wraps each call in a `Mono` and offloads it to Reactor's `boundedElastic` scheduler so the WebFlux event loop is never blocked.\n\nThis is one of several interchangeable notification adapters in the framework. Sibling adapters include\n[`fireflyframework-notifications-resend`](https://github.com/fireflyframework/fireflyframework-notifications-resend) (email),\n[`fireflyframework-notifications-twilio`](https://github.com/fireflyframework/fireflyframework-notifications-twilio) (SMS),\nand [`fireflyframework-notifications-firebase`](https://github.com/fireflyframework/fireflyframework-notifications-firebase) (push), all targeting the same core SPIs.\n\n## Features\n\n- **Reactive `EmailProvider` implementation** (`SendGridEmailProvider`) returning `Mono\u003cEmailResponseDTO\u003e`, with the blocking SendGrid SDK isolated on `Schedulers.boundedElastic()`.\n- **SendGrid v3 Mail Send API** via the official `com.sendgrid:sendgrid-java` client (`POST mail/send`).\n- **Rich message support** — single recipient with multiple **CC** and **BCC** addresses, **subject**, and body as either `text/html` (preferred when `html` is set) or `text/plain`.\n- **Attachments** — binary `EmailAttachmentDTO` content is Base64-encoded and sent inline with content type, filename, and `attachment` disposition.\n- **Message-ID capture** — extracts SendGrid's `X-Message-Id` response header into the `EmailResponseDTO` for correlation and delivery tracking.\n- **Robust result mapping** — HTTP 2xx maps to `EmailResponseDTO.success(messageId)`; non-2xx responses and `IOException`s map to `EmailResponseDTO.error(...)` instead of throwing.\n- **Spring Boot 3 auto-configuration** — activates only when `firefly.notifications.email.provider=sendgrid`, the SendGrid class is present, and an API key is configured; all beans are `@ConditionalOnMissingBean`, so your own definitions always win.\n- **Drop-in adapter** — include the dependency alongside `fireflyframework-notifications-core`; no SendGrid types leak into application code.\n\n## Requirements\n\n- Java 21+ (Java 25 recommended)\n- Spring Boot 3.x\n- Maven 3.9+\n- A [SendGrid](https://www.twilio.com/en-us/sendgrid/email-api) account and a v3 **API key** with `Mail Send` permission\n- A verified SendGrid **sender identity** (single sender or authenticated domain) for the `from` address\n- `fireflyframework-notifications-core` on the classpath (provides the `EmailProvider` SPI and `EmailService` facade)\n\n## Installation\n\nAdd the adapter alongside the notifications core. Versions are managed by the Firefly Framework parent/BOM, so you should not need to pin them explicitly.\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.fireflyframework\u003c/groupId\u003e\n    \u003cartifactId\u003efireflyframework-notifications-sendgrid\u003c/artifactId\u003e\n    \u003c!-- version managed by the Firefly BOM / parent --\u003e\n\u003c/dependency\u003e\n```\n\nThis module declares a transitive dependency on `fireflyframework-notifications-core`, so adding it pulls in the `EmailProvider` SPI automatically. If you inherit the Firefly parent POM, you can omit the `\u003cversion\u003e`:\n\n```xml\n\u003cparent\u003e\n    \u003cgroupId\u003eorg.fireflyframework\u003c/groupId\u003e\n    \u003cartifactId\u003efireflyframework-parent\u003c/artifactId\u003e\n    \u003cversion\u003e26.05.07\u003c/version\u003e\n\u003c/parent\u003e\n```\n\n## Quick Start\n\n**1. Add the dependencies** (core + this adapter):\n\n```xml\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.fireflyframework\u003c/groupId\u003e\n        \u003cartifactId\u003efireflyframework-notifications-core\u003c/artifactId\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.fireflyframework\u003c/groupId\u003e\n        \u003cartifactId\u003efireflyframework-notifications-sendgrid\u003c/artifactId\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n**2. Select SendGrid and provide your API key** in `application.yml`:\n\n```yaml\nfirefly:\n  notifications:\n    email:\n      provider: sendgrid       # selects this adapter\n    sendgrid:\n      api-key: ${SENDGRID_API_KEY}\n```\n\n**3. Inject the core `EmailService`** and send — your code never touches SendGrid types:\n\n```java\nimport org.fireflyframework.notifications.core.services.email.v1.EmailService;\nimport org.fireflyframework.notifications.interfaces.dtos.email.v1.EmailRequestDTO;\nimport org.fireflyframework.notifications.interfaces.dtos.email.v1.EmailResponseDTO;\nimport reactor.core.publisher.Mono;\n\n@Service\npublic class WelcomeMailer {\n\n    private final EmailService emailService;\n\n    public WelcomeMailer(EmailService emailService) {\n        this.emailService = emailService;\n    }\n\n    public Mono\u003cEmailResponseDTO\u003e sendWelcome(String to) {\n        EmailRequestDTO request = new EmailRequestDTO();\n        request.setFrom(\"noreply@example.com\");   // a verified SendGrid sender\n        request.setTo(to);\n        request.setSubject(\"Welcome to Firefly\");\n        request.setHtml(\"\u003ch1\u003eWelcome!\u003c/h1\u003e\u003cp\u003eThanks for signing up.\u003c/p\u003e\");\n        return emailService.sendEmail(request);\n    }\n}\n```\n\nThe auto-configuration builds the `SendGrid` client and the `SendGridEmailProvider` bean for you. The returned `EmailResponseDTO`\ncarries `success`/`error` status and, on success, the SendGrid `X-Message-Id`.\n\nYou can also depend on the `EmailProvider` SPI directly if you prefer to bypass the `EmailService` facade — the same `SendGridEmailProvider` bean satisfies it.\n\n## Configuration\n\nAll properties live under the `firefly.notifications` prefix. This adapter binds a single\n`@ConfigurationProperties` class, `SendGridProperties` (prefix `firefly.notifications.sendgrid`).\n\n```yaml\nfirefly:\n  notifications:\n    email:\n      provider: sendgrid          # required: activates this adapter\n    sendgrid:\n      api-key: ${SENDGRID_API_KEY} # required: SendGrid v3 API key with Mail Send permission\n```\n\n| Property | Description | Default |\n| --- | --- | --- |\n| `firefly.notifications.email.provider` | Selects the active email adapter. Must equal `sendgrid` for this module's auto-configuration to activate. | _(none)_ |\n| `firefly.notifications.sendgrid.api-key` | SendGrid v3 API key used to authenticate the `SendGrid` client. Required for the `SendGrid` bean to be created. Keep it out of source control (use an environment variable or secret manager). | _(none)_ |\n\nNotes:\n\n- The sender (`from`) address and recipients are supplied **per message** on the `EmailRequestDTO`, not via configuration — there are no global `from-email` / `from-name` properties. Ensure the `from` address is a SendGrid-verified sender or authenticated domain, otherwise SendGrid rejects the send.\n- All adapter beans are `@ConditionalOnMissingBean`. To override delivery behaviour, declare your own `SendGrid` or `EmailProvider` bean and the auto-configured one steps aside.\n\n## How It Works\n\n`SendGridAutoConfiguration` activates only when `firefly.notifications.email.provider=sendgrid` **and** `com.sendgrid.SendGrid` is on the classpath. It then:\n\n1. Creates a `SendGrid` client from `firefly.notifications.sendgrid.api-key` (only when the key is present).\n2. Registers `SendGridEmailProvider` as the `EmailProvider`, unless another `EmailProvider` bean already exists.\n\nOn each `sendEmail(...)` call, `SendGridEmailProvider` builds a SendGrid `Mail` (mapping subject, HTML/text content, CC, BCC, and Base64-encoded attachments), issues a `POST mail/send`, and maps the result: 2xx -\u003e `EmailResponseDTO.success(X-Message-Id)`, anything else (or an `IOException`) -\u003e `EmailResponseDTO.error(...)`. The whole call runs via `Mono.fromCallable(...).subscribeOn(Schedulers.boundedElastic())` to keep blocking I/O off the reactive event loop.\n\n## Documentation\n\n- Firefly Framework documentation hub and module catalog: [github.com/fireflyframework](https://github.com/fireflyframework)\n- Notifications core SPI and `EmailService` facade: [`fireflyframework-notifications-core`](https://github.com/fireflyframework/fireflyframework-notifications)\n- SendGrid v3 Mail Send API reference: [docs.sendgrid.com — Mail Send](https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send)\n\n## Contributing\n\nContributions are welcome. Please read the [CONTRIBUTING.md](CONTRIBUTING.md) guide for details on our code of conduct, development process, and how to submit pull requests.\n\n## License\n\nCopyright 2024-2026 Firefly Software Foundation.\n\nLicensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffireflyframework%2Ffireflyframework-notifications-sendgrid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffireflyframework%2Ffireflyframework-notifications-sendgrid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffireflyframework%2Ffireflyframework-notifications-sendgrid/lists"}