The Notification API is a REST API designed for sending notifications, managing notification templates, and easily setting up delivery providers. It also offers centralized tracking and auditing, enabling you to monitor notification delivery, volume, success rates, and more from a single interface. Regardless of whether notifications are sent from different applications using various providers (such as SendGrid, SMTP, or REST API calls), you can track and manage them all from this unified platform.
- Why use the Notification API?
- Features
- Technologies
- Database
- Platforms
- Providers
- Templates
- Notifications
- Frequently Asked Questions
- License
-
Centralized Notification Management: The Notification API provides a single interface send, track and manage all notifications sent from different applications. No matter what provider (e.g., SendGrid, SMTP, or custom HTTP clients) is used, you can monitor delivery status, success rates, and volumes from one place.
-
Simplifies Development: Forget about writing custom code for every application that needs to send notifications. Instead, set up your notification providers and templates once. All your applications can then send notifications by simply making a call to the Notification API, reducing code duplication and maintenance.
-
Unified Template Management: Manage all your notification templates in one place. Templates can include placeholders that are dynamically replaced when sending notifications, making it easy to personalize messages without adding complexity to your code.
-
Resend and Retry Made Easy: The Notification API automatically retries failed delivery attempts, with up to 5 retries before marking the notification as failed. If all retries fail, the failure is logged for auditing. Additionally, you can easily query and manually resend notifications via the API, providing a robust and reliable solution for handling failures without manual intervention.
-
Boost Productivity: By offloading notification logic to the API, development teams can focus on core features. Once providers and templates are set up, sending notifications becomes a simple API call.
- 🔧 Highly flexible and configurable
- 🗄️ Dedicated database for storage
- ⚙️ Generic and flexible design for use in many different applications
- 🔌 Easily integrable with any application
- .NET 8.0
- MongoDB
- Docker
- Kubernetes
The Notification API utilizes its own NoSQL database, MongoDB, which includes the following collections:
- Platforms: Stores information about the platforms or applications configured to use the API.
- Providers: Contains details of the delivery providers configured for each platform.
- Templates: Maintains the templates configured for each platform and notification type.
- Notifications: Tracks all notifications that have been sent or attempted.
To use the Notification API, an API Key is required.
Each platform or application that intends to use the Notification API must be registered via the following endpoint:
Route: /api/v1/notification/platforms
HTTP Verb: POST
Content-Type: application/json
You must provide the following details:
- name: The name of the platform or application
- description: A description of the platform or application
After successful registration, an API Key will be provided for accessing the Notification API. Be sure to keep this key safe.
Example: Registering a Platform
{
"name": "ClientExpensesApp",
"description": "Mobile app used to track client's expenses"
}In order to send notifications, the API needs to know which deelivery provider to use.
But... what is a Provider?
A provider is a service, either internal or third-party, used for sending emails, SMS, or other notifications. The API allows for dynamic configuration of these providers. You can set up providers such as SendGrid, SMTP or REST API calls.
Example: Registering a SendGrid Provider
{
"name": "ClientExpensesSendGrid",
"type": "SendGrid",
"settings": {
"sendGrid": {
"fromEmail": "noreply@clientexpenses.com",
"fromDisplayName": "Client Expenses",
"apiKey": "yourSendGridApiKey"
}
},
"isActive": true,
"isPublic": false
}Example: Registering an SMTP Provider
{
"name": "ClientExpensesOutlook",
"type": "SMTP",
"settings": {
"smtp": {
"fromEmail": "notifications@clientexpenses.com",
"fromDisplayName": "Client Expenses",
"host": "outlook.office365.com",
"port": 993,
"password": "yourSMTPServerPassword"
}
},
"isActive": true,
"isPublic": true
}The API provides an operation to register the templates that your application may send.
Route: /api/v1/notification/templates HTTP Verb: POST Content-Type: application/json
The request must include:
- name: The name of the template
- platformName: The platform or application associated with the template
- notificationType: The type of notification (Email, SMS)
- language: The language of the template (e.g., "es" for Spanish, "en" for English)
- subject: The subject line of the email (if it's an email)
- content: The content of the template (may be a simple text or HTML)
- metadata []: An array specifying placeholders required by the template, which must be replaced at runtime. Each placeholder should include:
- key: The placeholder name
- description: A description of the placeholder
- isRequired: Indicates whether the placeholder is mandatory
Example: Registering a User Registration Template
{
"name": "UserRegistration",
"notificationType": "Email",
"subject": "User registration confirmation",
"language": "en",
"content": "Hi $[Username], thanks for your registration in our app!",
"metadata": [
{
"key": "Username",
"description": "User's name",
"isRequired": true
}
]
}The API tracks all notifications that have been sent or attempted, regardless of success or failure.
When sending a notification, a notificationId is returned, which can be used to:
- Query the notification
- Resend the notification
You can query the notifications sent or delivery attempts and view information such as:
- notificationId: Unique identifier of the notification
- toDestination: Email address/phone number of the recipient
- templateName: Name of the template used
- platformName: Name of the platform
- date: Date and time the request was made
- success: Indicates whether it was successful or failed
- request: Request body provided for sending the notification
- parentNotificationId: If the notification was resent from another, specifies the notificationId of the parent notification
To resend a notification, provide the notificationId of the original notification. The API will resend the notification with a new notificationId and link it to the original notification using the parentNotificationId property.
What types of notifications are sent?
Currently, the API supports sending notifications via email natively, while SMS, push notifications, and other types are handled through providers configured as HTTP clients (REST API calls).
Who can use the API?
Any application that needs to send notifications.
Do notifications have to be sent with templates?
Yes, notifications must be sent using pre-configured templates. Refer to the Templates section for more information.
What happens if a notification fails to send?
The Notification API automatically retries sending failed notifications up to five times. If it still fails, it will be logged for auditing, and you can manually resend it if needed.
Can I customize my notification providers?
Yes, you can configure different providers for sending notifications, including SendGrid, SMTP, or REST API calls. This flexibility allows you to choose the best service for your needs.
Do I need to set up providers to send notifications?
Yes, you must set up at least one provider to send notifications using the Notification API. The API does not send notifications by itself; instead, it relies on the configured providers (like SendGrid, SMTP, or REST API calls) to deliver the notifications. This setup is essential for ensuring that notifications are sent correctly through the desired channels.
What is the purpose of creating a Platform?
Creating a Platform in the Notification API identifies the specific application or system sending the notifications. This setup allows for better tracking and auditing of notifications, helping you monitor which application is responsible for each notification sent. It also ensures that each application can manage its notifications independently and securely.
How are templates scoped within the Notification API?
All templates created by a platform belong exclusively to that platform. This ensures that templates are tailored to the specific needs of each application, allowing for effective management and personalization of notifications.
How are providers scoped within the Notification API?
Providers can be associated with a specific platform or marked as public. Public providers can be used by any platform, while private providers are restricted to the platform that created them, providing flexibility in how notifications are delivered.
Can one platform view the templates and notifications sent by another platform?
No, each platform operates independently within the Notification API. Templates and notifications created or sent by one platform are not visible to or accessible by other platforms, ensuring data privacy and separation between applications.
Is it necessary to create a platform and use the API key generated for that platform to interact with the API?
Yes, you need to create a platform to use the Notification API. Each platform gets a unique API key that you must include in your requests. This key ensures that only registered applications can send notifications and manage their templates and providers. It also helps identify which application is interacting the API.
Designed and developed by:
Omarky Tejeda | Software Engineer
Open Source?.. Why not?