Skip to main content

​
Endpoint

POST /api/v1/notifications

​
Description

Submits a notification request to the API Gateway. The gateway validates the request, queues it in RabbitMQ, and returns a confirmation with a notification ID for tracking.

​
Authentication

This endpoint requires authentication. Include valid credentials in your request headers.

​
Request Body

​
notification_type
enum
required
Type of notification to send.Allowed values: email, push
​
user_id
string (UUID)
required
User ID in UUID format.Example: 123e4567-e89b-12d3-a456-426614174000Validation: Must be a valid UUID v4 format
​
template_code
string
required
Template code to use for the notification. The template must exist in the Template Service.Example: welcome_email, password_reset
​
variables
object
required
Variables to populate in the template. Structure depends on the template being used.
​
request_id
string
required
Unique request ID for idempotency. Use this to prevent duplicate notifications.Example: req-123e4567-e89b-12d3-a456-426614174000
​
priority
number
Priority level for the notification. Higher numbers indicate higher priority.Range: 1-5Default: 1Example: 1
​
metadata
object
Additional metadata for the notification request. Can contain any JSON-serializable data.Example: {"title": "Welcome!"}

​
Response

​
success
boolean
Indicates whether the request was successful
​
data
object
Response data object
​
message
string
Human-readable message describing the resultExample: Notification queued successfully

​
Error Responses

​
400 Bad Request
error
Returned when the request payload is invalid or missing required fields.Example scenarios:
  • Invalid UUID format for user_id
  • Missing required fields
  • Invalid notification_type value
  • Priority outside 1-5 range
​
401 Unauthorized
error
Returned when authentication credentials are missing or invalid.
​
500 Internal Server Error
error
Returned when an unexpected error occurs on the server.Example scenarios:
  • RabbitMQ connection failure
  • Database connectivity issues

​
Example Request

curl -X POST http://localhost:8000/api/v1/notifications \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "notification_type": "email",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "template_code": "welcome_email",
    "variables": {
      "name": "John Doe",
      "link": "https://example.com/welcome",
      "meta": {
        "campaign": "onboarding"
      }
    },
    "request_id": "req-123e4567-e89b-12d3-a456-426614174000",
    "priority": 1,
    "metadata": {
      "title": "Welcome to Our Platform"
    }
  }'

​
Example Response

200 Success
{
  "success": true,
  "data": {
    "notification_id": "req-123e4567-e89b-12d3-a456-426614174000",
    "status": "queued"
  },
  "message": "Notification queued successfully"
}
400 Bad Request
{
  "success": false,
  "message": "Validation failed",
  "error": [
    "user_id must be a valid UUID",
    "priority must not be greater than 5"
  ]
}
401 Unauthorized
{
  "success": false,
  "message": "Unauthorized",
  "error": "Invalid or missing authentication token"
}

​
Notes

  • The request_id field enables idempotency - sending the same request_id multiple times will not create duplicate notifications
  • Notifications are queued asynchronously in RabbitMQ (email.queue or push.queue based on notification_type)
  • The gateway validates user existence and template availability before queuing
  • Status updates can be tracked using the returned notification_id

Build docs developers (and LLMs) love

Get started for freeTalk to us