Notifications

User notification retrieval and management (Inbox service)

Get user notifications

get

/notifications

Retrieves paginated notifications for the authenticated user, including both user-specific and broadcast notifications. The user's address is extracted from the signed fetch authentication chain.

Authorizations

AuthorizationstringRequired

Signed fetch authentication using @dcl/platform-crypto-middleware implementing Decentraland's ADR-44.

Requirements:

• Authentication chain headers: x-identity, x-signature, x-timestamp
• Token expiration: 5 minutes
• Metadata validation: Rejects requests with signer: "decentraland-kernel-scene"
• The user's Ethereum address is extracted from the auth chain

Example:

Authorization: Bearer <signed-fetch-token>
x-identity: <auth-chain-json>
x-signature: <signature>
x-timestamp: <timestamp>

Query parameters

fromintegerOptional

Unix timestamp in milliseconds. Only return notifications with timestamp >= this value

Example: 1701379983000

limitinteger · min: 1 · max: 50Optional

Maximum number of notifications to return (capped at 50)

Default: 20

onlyUnreadbooleanOptional

If present (value doesn't matter), only unread notifications are returned

Responses

200

User notifications retrieved successfully

application/json

401

Unauthorized - invalid or missing signed fetch headers

application/json

403

Forbidden - signed fetch metadata validation failed (e.g., request from decentraland-kernel-scene)

application/json

get/notifications

GET /notifications HTTP/1.1
Host: notifications.decentraland.org
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "notifications": [
    {
      "id": "3a33a38a-e17a-4153-926b-c18f1e57e3e1",
      "type": "bid_accepted",
      "address": "0xb5D7D1A05f553b5098D9274Df6B292e4e8222314",
      "metadata": {
        "link": "https://decentraland.zone/marketplace/contracts/0x5d670bab052f21c3b1984231b1187be34852db24/tokens/105312291668557186697918027683670432318895095400549111254310977537",
        "title": "Bid Accepted"
      },
      "timestamp": "1701379983",
      "read": false
    }
  ]
}

Mark notifications as read

put

/notifications/read

Marks specified notifications as read for the authenticated user. This operation is irreversible. The user's address is extracted from the signed fetch authentication chain.

Authorizations

AuthorizationstringRequired

Signed fetch authentication using @dcl/platform-crypto-middleware implementing Decentraland's ADR-44.

Requirements:

• Authentication chain headers: x-identity, x-signature, x-timestamp
• Token expiration: 5 minutes
• Metadata validation: Rejects requests with signer: "decentraland-kernel-scene"
• The user's Ethereum address is extracted from the auth chain

Example:

Authorization: Bearer <signed-fetch-token>
x-identity: <auth-chain-json>
x-signature: <signature>
x-timestamp: <timestamp>

Body

notificationIdsstring · uuid[] · min: 1Required

Array of notification IDs to mark as read

Responses

200

Notifications marked as read successfully

application/json

updatedintegerRequired

Number of notifications successfully marked as read

Example: 2

400

Bad request - missing or invalid notificationIds array

application/json

401

Unauthorized - invalid or missing signed fetch headers

application/json

403

Forbidden - signed fetch metadata validation failed

application/json

put/notifications/read

PUT /notifications/read HTTP/1.1
Host: notifications.decentraland.org
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 99

{
  "notificationIds": [
    "3a33a38a-e17a-4153-926b-c18f1e57e3e1",
    "f098bed0-bff9-4ebe-a160-5687ffa4fe36"
  ]
}

{
  "updated": 2
}

Send common email notification

post

/notifications/email

Sends a generic email notification using a common template. Used by internal services to send custom email notifications. Available only in the Inbox service.

Authorizations

AuthorizationstringRequired

Bearer token authentication using a shared API key (NOTIFICATION_SERVICE_TOKEN). Used for service-to-service communication and external notification publishing.

Example:

Authorization: Bearer <api-key>

Body

emailstring · emailRequired

Recipient email address

subjectstringRequired

Email subject line

contentstringRequired

Email body content (HTML)

titlestringOptional

Optional title for the email template

Default: New

titleHighlightstringOptional

Optional highlighted portion of the title

Default: Notification

Responses

204

Email sent successfully

No content

400

Invalid request - missing required fields

application/json

401

Unauthorized - missing or invalid API key

application/json

post/notifications/email

POST /notifications/email HTTP/1.1
Host: notifications.decentraland.org
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 106

{
  "email": "[email protected]",
  "subject": "text",
  "content": "text",
  "title": "New",
  "titleHighlight": "Notification"
}

No content