# Notifications User notification retrieval and management (Inbox service) ## Get user 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.
````json {"openapi":"3.1.0","info":{"title":"Notifications Workers API","version":"1.0.0"},"tags":[{"name":"Notifications","description":"User notification retrieval and management (Inbox service)"}],"servers":[{"url":"https://notifications.decentraland.org","description":"Production environment"},{"url":"https://notifications.decentraland.zone","description":"Development environment"}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"http","scheme":"bearer","description":"Signed fetch authentication using @dcl/platform-crypto-middleware implementing Decentraland's ADR-44.\n\n**Requirements:**\n- Authentication chain headers: `x-identity`, `x-signature`, `x-timestamp`\n- Token expiration: 5 minutes\n- Metadata validation: Rejects requests with `signer: \"decentraland-kernel-scene\"`\n- The user's Ethereum address is extracted from the auth chain\n\n**Example:**\n```\nAuthorization: Bearer \nx-identity: \nx-signature: \nx-timestamp: \n```\n"}}},"paths":{"/notifications":{"get":{"summary":"Get user notifications","description":"Retrieves paginated notifications for the authenticated user, including both user-specific and broadcast notifications.\nThe user's address is extracted from the signed fetch authentication chain.\n","operationId":"getNotifications","tags":["Notifications"],"parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Unix timestamp in milliseconds. Only return notifications with timestamp >= this value"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Maximum number of notifications to return (capped at 50)"},{"name":"onlyUnread","in":"query","required":false,"schema":{"type":"boolean"},"description":"If present (value doesn't matter), only unread notifications are returned"}],"responses":{"200":{"description":"User notifications retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"notifications":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique notification identifier"},"type":{"type":"string","description":"Notification type (from NotificationType enum)"},"address":{"oneOf":[{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},{"type":"null"}],"description":"User's Ethereum address (null for broadcast notifications)"},"metadata":{"type":"object","description":"Notification-specific metadata containing details like links, titles, descriptions, etc.","additionalProperties":true},"timestamp":{"type":"string","description":"Unix timestamp (in seconds) when the notification event occurred"},"read":{"type":"boolean","description":"Whether the notification has been marked as read by the user"}},"required":["id","type","address","metadata","timestamp","read"]},"description":"List of notifications for the user"}},"required":["notifications"]}}}},"401":{"description":"Unauthorized - invalid or missing signed fetch headers","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type or category"},"message":{"type":"string","description":"Detailed error message"},"code":{"type":"string","description":"Optional error code for programmatic error handling"}},"required":["error"]}}}},"403":{"description":"Forbidden - signed fetch metadata validation failed (e.g., request from decentraland-kernel-scene)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type or category"},"message":{"type":"string","description":"Detailed error message"},"code":{"type":"string","description":"Optional error code for programmatic error handling"}},"required":["error"]}}}}}}}}} ```` ## Mark notifications as 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.
````json {"openapi":"3.1.0","info":{"title":"Notifications Workers API","version":"1.0.0"},"tags":[{"name":"Notifications","description":"User notification retrieval and management (Inbox service)"}],"servers":[{"url":"https://notifications.decentraland.org","description":"Production environment"},{"url":"https://notifications.decentraland.zone","description":"Development environment"}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"http","scheme":"bearer","description":"Signed fetch authentication using @dcl/platform-crypto-middleware implementing Decentraland's ADR-44.\n\n**Requirements:**\n- Authentication chain headers: `x-identity`, `x-signature`, `x-timestamp`\n- Token expiration: 5 minutes\n- Metadata validation: Rejects requests with `signer: \"decentraland-kernel-scene\"`\n- The user's Ethereum address is extracted from the auth chain\n\n**Example:**\n```\nAuthorization: Bearer \nx-identity: \nx-signature: \nx-timestamp: \n```\n"}}},"paths":{"/notifications/read":{"put":{"summary":"Mark notifications as read","description":"Marks specified notifications as read for the authenticated user. This operation is irreversible.\nThe user's address is extracted from the signed fetch authentication chain.\n","operationId":"markNotificationsAsRead","tags":["Notifications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"notificationIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"description":"Array of notification IDs to mark as read"}},"required":["notificationIds"]}}}},"responses":{"200":{"description":"Notifications marked as read successfully","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"integer","description":"Number of notifications successfully marked as read"}},"required":["updated"]}}}},"400":{"description":"Bad request - missing or invalid notificationIds array","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type or category"},"message":{"type":"string","description":"Detailed error message"},"code":{"type":"string","description":"Optional error code for programmatic error handling"}},"required":["error"]}}}},"401":{"description":"Unauthorized - invalid or missing signed fetch headers","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type or category"},"message":{"type":"string","description":"Detailed error message"},"code":{"type":"string","description":"Optional error code for programmatic error handling"}},"required":["error"]}}}},"403":{"description":"Forbidden - signed fetch metadata validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type or category"},"message":{"type":"string","description":"Detailed error message"},"code":{"type":"string","description":"Optional error code for programmatic error handling"}},"required":["error"]}}}}}}}}} ```` ## Send common email notification > Sends a generic email notification using a common template. Used by internal services to send custom email notifications.\ > Available only in the Inbox service.
````json {"openapi":"3.1.0","info":{"title":"Notifications Workers API","version":"1.0.0"},"tags":[{"name":"Notifications","description":"User notification retrieval and management (Inbox service)"}],"servers":[{"url":"https://notifications.decentraland.org","description":"Production environment"},{"url":"https://notifications.decentraland.zone","description":"Development environment"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication using a shared API key (`NOTIFICATION_SERVICE_TOKEN`).\nUsed for service-to-service communication and external notification publishing.\n\n**Example:**\n```\nAuthorization: Bearer \n```\n"}}},"paths":{"/notifications/email":{"post":{"summary":"Send common email notification","description":"Sends a generic email notification using a common template. Used by internal services to send custom email notifications.\nAvailable only in the Inbox service.\n","operationId":"sendCommonEmail","tags":["Notifications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Recipient email address"},"subject":{"type":"string","description":"Email subject line"},"content":{"type":"string","description":"Email body content (HTML)"},"title":{"type":"string","description":"Optional title for the email template","default":"New"},"titleHighlight":{"type":"string","description":"Optional highlighted portion of the title","default":"Notification"}},"required":["email","subject","content"]}}}},"responses":{"204":{"description":"Email sent successfully"},"400":{"description":"Invalid request - missing required fields","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type or category"},"message":{"type":"string","description":"Detailed error message"},"code":{"type":"string","description":"Optional error code for programmatic error handling"}},"required":["error"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type or category"},"message":{"type":"string","description":"Detailed error message"},"code":{"type":"string","description":"Optional error code for programmatic error handling"}},"required":["error"]}}}}}}}}} ```` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.decentraland.org/apis/apis/notifications-workers/notifications.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.