Notification Service API

Overview

The Notification Service manages user notifications across multiple delivery channels. It handles notification creation, delivery preferences, push notification registration, and email unsubscribe management. Key Features:

Push notifications (iOS and Android)
Email notifications with templates
Device registration and management
Notification preferences and unsubscribe
Multi-channel delivery

Architecture:

RESTful HTTP API
PostgreSQL for notification storage
AWS SNS for push delivery
Integration with email service
Event-driven notification creation

User Notifications

List User Notifications

Get paginated list of notifications for the authenticated user.

curl https://api.macro.com/v1/user_notifications?limit=20 \
  -H "Authorization: Bearer YOUR_TOKEN"

limit

integer

default:"20"

Number of notifications to return per page

cursor

string

Pagination cursor from previous response (base64 encoded)

items

array

Array of notification objects

items[].notificationId

uuid

Unique notification identifier

items[].ownerId

string

User ID who owns this notification

items[].notificationEventType

string

Event type: channel_mention, item_share, channel_invite, etc.

items[].entityType

string

Type of entity: document, channel, message, etc.

items[].entityId

string

ID of the entity this notification refers to

items[].sent

boolean

Whether notification has been delivered

items[].done

boolean

Whether user marked notification as done

items[].viewedAt

timestamp

When user viewed the notification

items[].createdAt

timestamp

Notification creation time

items[].senderId

string

User who triggered the notification

items[].notificationMetadata

object

Event-specific metadata (message text, share details, etc.)

nextCursor

string

Cursor for fetching next page of results

Get Notification by ID

Retrieve a single notification by its ID.

curl https://api.macro.com/v1/user_notifications/{notification_id} \
  -H "Authorization: Bearer YOUR_TOKEN"

notificationId

uuid

Notification identifier

notificationEventType

string

Type of notification event

entityType

string

Entity type (document, channel, message)

entityId

string

Entity identifier

sent

boolean

Delivery status

notificationMetadata

object

Event-specific data

Get Notifications by Event Item

Get all notifications for a specific event item (e.g., all notifications about a particular document).

curl https://api.macro.com/v1/user_notifications/item/{event_item_id} \
  -H "Authorization: Bearer YOUR_TOKEN"

event_item_id

uuid

required

The entity/event ID to get notifications for

items

array

Notifications related to this event item

nextCursor

string

Pagination cursor

Bulk Get by Event Items

Retrieve notifications for multiple event items in a single request.

curl -X POST https://api.macro.com/v1/user_notifications/item/bulk \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventItemIds": [
      "doc_123",
      "channel_456",
      "message_789"
    ]
  }'

eventItemIds

array

required

Array of event item IDs to fetch notifications for

items

array

All notifications matching the provided event item IDs

Delete Notification

Delete a specific notification.

curl -X DELETE https://api.macro.com/v1/user_notifications/{notification_id} \
  -H "Authorization: Bearer YOUR_TOKEN"

Bulk Delete Notifications

Delete multiple notifications at once.

curl -X DELETE https://api.macro.com/v1/user_notifications/bulk \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notificationIds": [
      "notif_123",
      "notif_456"
    ]
  }'

notificationIds

array

required

Array of notification IDs to delete

Device Management

Register Device for Push Notifications

curl -X POST https://api.macro.com/v1/device/register \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "DEVICE_FCM_OR_APNS_TOKEN",
    "deviceType": "ios"
  }'

token

string

required

Device push token from FCM (Android) or APNs (iOS)

deviceType

string

required

Device platform: ios or android

success

boolean

Registration success status

How it works:

Service creates/updates SNS platform endpoint for device
Associates endpoint with user in database
Enables endpoint for push delivery
Updates token if device re-registers

Unregister Device

Remove a device from receiving push notifications.

curl -X DELETE https://api.macro.com/v1/device/unregister \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "DEVICE_TOKEN"
  }'

token

string

required

Device push token to unregister

Unsubscribe Management

Unsubscribe from Item Notifications

Stop receiving notifications about a specific item (document, channel, etc.).

curl -X POST https://api.macro.com/v1/unsubscribe/item \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "document",
    "entityId": "doc_123"
  }'

entityType

string

required

Type of entity to unsubscribe from: document, channel, message

entityId

string

required

ID of the specific entity

Unsubscribe from Email Notifications

Opt out of email notifications entirely.

curl -X POST https://api.macro.com/v1/unsubscribe/email \
  -H "Authorization: Bearer YOUR_TOKEN"

Unsubscribe from All Notifications

Completely opt out of all notification types.

curl -X POST https://api.macro.com/v1/unsubscribe/all \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Unsubscribe Preferences

Retrieve user’s current notification preferences.

curl https://api.macro.com/v1/unsubscribe \
  -H "Authorization: Bearer YOUR_TOKEN"

emailUnsubscribed

boolean

Whether user opted out of email notifications

allUnsubscribed

boolean

Whether user opted out of all notifications

itemUnsubscribes

array

List of specific items user unsubscribed from

itemUnsubscribes[].entityType

string

Entity type unsubscribed from

itemUnsubscribes[].entityId

string

Entity ID unsubscribed from

Remove Item Unsubscribe

Re-enable notifications for a previously unsubscribed item.

curl -X DELETE https://api.macro.com/v1/unsubscribe/item \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "document",
    "entityId": "doc_123"
  }'

Notification Types

The service supports various notification event types:

Channel Notifications

channel_mention

User mentioned in a channel messageMetadata:

channelId: Channel where mention occurred
messageId: Message containing the mention
messageText: Preview of message content
senderName: Name of user who mentioned

channel_invite

User invited to join a channelMetadata:

channelId: Channel user was invited to
channelName: Name of the channel
inviterId: User who sent invite
inviterName: Name of inviter

channel_message

New message in a subscribed channelMetadata:

channelId: Channel with new message
messageId: New message ID
messageText: Message preview
senderName: Message author

Document Notifications

item_share

comment_mention

User mentioned in document commentMetadata:

documentId: Document with comment
commentId: Comment containing mention
commentText: Comment preview
mentionerId: User who mentioned

Push Notification Format

iOS (APNs) Payload

{
  "aps": {
    "alert": {
      "title": "New Message",
      "body": "Alice mentioned you in #general"
    },
    "badge": 5,
    "sound": "default",
    "mutable-content": 1
  },
  "data": {
    "notificationId": "123e4567-e89b-12d3-a456-426614174000",
    "senderProfilePictureUrl": "https://cdn.macro.com/avatar/alice.jpg"
  }
}

Android (FCM) Payload

{
  "notification": {
    "title": "New Message",
    "body": "Alice mentioned you in #general"
  },
  "data": {
    "notificationId": "123e4567-e89b-12d3-a456-426614174000",
    "senderProfilePictureUrl": "https://cdn.macro.com/avatar/alice.jpg"
  }
}

Email Templates

Notifications can be delivered via email using pre-defined templates:

Channel Message Template

Subject: New message in Body includes:

Sender name and profile picture
Message preview
Link to channel
Unsubscribe link

Subject: shared with you Body includes:

Document name and preview
Sharer information
Access level granted
Link to document
Unsubscribe options

Processing Patterns

Async Notification Creation

Notifications are created asynchronously:

Event Trigger: Action occurs (message sent, document shared)
Queue Message: Event published to notification ingress
Process: Notification service consumes event
Create: Notification record created in database
Deliver: Push/email sent based on user preferences

Delivery Channels

Notifications are delivered via multiple channels:

Push: Real-time mobile notifications via SNS
Email: Templated email via email service
In-app: Retrieved via API for in-app notification center

Batching

Multiple notifications for the same entity are batched:

Prevents notification spam
Combines multiple mentions into single alert
Configurable batching window (default: 5 minutes)

Error Handling

Push Delivery Failures

When push notifications fail:

Invalid tokens trigger device unregistration
Expired endpoints are recreated on next device registration
Failed deliveries logged for monitoring

Email Delivery Failures

Email notification failures:

Bounce handling via email service
Hard bounces trigger email unsubscribe
Soft bounces are retried

Common Errors

Error	Cause	Resolution
`Invalid device token`	Token expired or invalid	Re-register device
`Endpoint disabled`	SNS endpoint disabled	Service automatically re-enables
`User not found`	Invalid user context	Check authentication
`Notification not found`	Invalid notification ID	Verify notification exists

Overview

Core Services

Processing Services

Notification Service API

Overview

User Notifications

List User Notifications

Get Notification by ID

Get Notifications by Event Item

Bulk Get by Event Items

Delete Notification

Bulk Delete Notifications

Device Management

Register Device for Push Notifications

Unregister Device

Unsubscribe Management

Unsubscribe from Item Notifications

Unsubscribe from Email Notifications

Unsubscribe from All Notifications

Get Unsubscribe Preferences

Remove Item Unsubscribe

Notification Types

Channel Notifications

Document Notifications

Push Notification Format

iOS (APNs) Payload

Android (FCM) Payload

Email Templates

Channel Message Template

Processing Patterns

Async Notification Creation

Delivery Channels

Batching

Error Handling

Push Delivery Failures

Email Delivery Failures

Common Errors

Build docs developers (and LLMs) love

Overview

Core Services

Processing Services

​Overview

​User Notifications

​List User Notifications

​Get Notification by ID

​Get Notifications by Event Item

​Bulk Get by Event Items

​Delete Notification

​Bulk Delete Notifications

​Device Management

​Register Device for Push Notifications

​Unregister Device

​Unsubscribe Management

​Unsubscribe from Item Notifications

​Unsubscribe from Email Notifications

​Unsubscribe from All Notifications

​Get Unsubscribe Preferences

​Remove Item Unsubscribe

​Notification Types

​Channel Notifications

​Document Notifications

​Push Notification Format

​iOS (APNs) Payload

​Android (FCM) Payload

​Email Templates

​Channel Message Template

​Item Share Template

​Processing Patterns

​Async Notification Creation

​Delivery Channels

​Batching

​Error Handling

​Push Delivery Failures

​Email Delivery Failures

​Common Errors

Build docs developers (and LLMs) love

Overview

User Notifications

List User Notifications

Get Notification by ID

Get Notifications by Event Item

Bulk Get by Event Items

Delete Notification

Bulk Delete Notifications

Device Management

Register Device for Push Notifications

Unregister Device

Unsubscribe Management

Unsubscribe from Item Notifications

Unsubscribe from Email Notifications

Unsubscribe from All Notifications

Get Unsubscribe Preferences

Remove Item Unsubscribe

Notification Types

Channel Notifications

Document Notifications

Push Notification Format

iOS (APNs) Payload

Android (FCM) Payload

Email Templates

Channel Message Template

Item Share Template

Processing Patterns

Async Notification Creation

Delivery Channels

Batching

Error Handling

Push Delivery Failures

Email Delivery Failures

Common Errors