Subscriptions

User subscription preferences and email verification (Inbox service)

Get user subscription preferences

get

/subscription

Retrieves the subscription preferences for the authenticated user, including confirmed email, unconfirmed email (if any), and detailed notification preferences for each notification type. If no subscription exists, returns default preferences with all notifications enabled.

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>

Responses

200

User subscription preferences retrieved successfully

application/json

emailone ofOptional

Confirmed email address (null if not set)

string · emailOptional

nullOptional

unconfirmedEmailone ofOptional

Email pending confirmation (null if no pending email)

string · emailOptional

nullOptional

401

Unauthorized - invalid or missing signed fetch headers

application/json

403

Forbidden - signed fetch metadata validation failed

application/json

get

/subscription

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

{
  "email": "[email protected]",
  "unconfirmedEmail": null,
  "details": {
    "ignore_all_email": false,
    "ignore_all_in_app": false,
    "message_type": {
      "bid_accepted": {
        "email": true,
        "in_app": true
      },
      "bid_received": {
        "email": true,
        "in_app": true
      }
    }
  }
}

Update subscription preferences

put

/subscription

Updates the subscription preferences for the authenticated user. Allows configuring global email/in-app preferences and per-notification-type preferences. The request is validated against the SubscriptionDetails schema. Sends an analytics event to the data warehouse.

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

ignore_all_emailbooleanRequired

If true, user will not receive any email notifications

ignore_all_in_appbooleanRequired

If true, user will not receive any in-app notifications

Responses

204

Subscription preferences updated successfully

400

Invalid request - validation error in subscription details

application/json

401

Unauthorized - invalid or missing signed fetch headers

application/json

403

Forbidden - signed fetch metadata validation failed

application/json

put

/subscription

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

{
  "ignore_all_email": false,
  "ignore_all_in_app": false,
  "message_type": {
    "bid_accepted": {
      "email": true,
      "in_app": true
    },
    "item_sold": {
      "email": false,
      "in_app": true
    }
  }
}

No content

Unsubscribe from all email notifications

get

/unsubscribe/{address}

Unsubscribes a user from all email notifications by setting ignore_all_email to true. The URL must be signed with HMAC-SHA256 using the service's signing key. Returns an HTML confirmation page. This endpoint is typically accessed via links in notification emails.

Path parameters

addressstringRequired

Ethereum address of the user

Example: 0xb5D7D1A05f553b5098D9274Df6B292e4e8222314Pattern: ^0x[a-fA-F0-9]{40}$

Query parameters

signaturestringRequired

HMAC-SHA256 signature of the URL path and query parameters

timestampstringRequired

Unix timestamp when the signature was generated

Responses

200

Successfully unsubscribed from all email notifications - returns HTML page

text/html

stringOptional

HTML confirmation page

400

Invalid signature or expired link

application/json

get

/unsubscribe/{address}

GET /unsubscribe/{address}?signature=text&timestamp=text HTTP/1.1
Host: notifications.decentraland.org
Accept: */*

text

Unsubscribe from specific notification type

get

/unsubscribe/{address}/{notificationType}

Unsubscribes a user from email notifications for a specific notification type. The URL must be signed with HMAC-SHA256 using the service's signing key. Returns an HTML confirmation page. This endpoint is typically accessed via links in notification emails.

Path parameters

addressstringRequired

Ethereum address of the user

Example: 0xb5D7D1A05f553b5098D9274Df6B292e4e8222314Pattern: ^0x[a-fA-F0-9]{40}$

notificationTypestringRequired

Notification type to unsubscribe from (must be a valid NotificationType enum value)

Example: bid_accepted

Query parameters

signaturestringRequired

HMAC-SHA256 signature of the URL path and query parameters

timestampstringRequired

Unix timestamp when the signature was generated

Responses

200

Successfully unsubscribed from notification type - returns HTML page

text/html

stringOptional

HTML confirmation page

400

Invalid signature, expired link, or invalid notification type

application/json

get

/unsubscribe/{address}/{notificationType}

GET /unsubscribe/{address}/{notificationType}?signature=text&timestamp=text HTTP/1.1
Host: notifications.decentraland.org
Accept: */*

text

Set or update email address

put

/set-email

Initiates email verification process by storing an unconfirmed email and sending a confirmation email.

If email is an empty string, removes the current email and disables email notifications
If email already exists for another address, returns an error
If email matches the currently confirmed email, skips verification
Otherwise, generates a 32-character code and sends verification email via SendGrid

The confirmation email contains a link that may include Turnstile challenge if the feature flag is enabled.

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

emailstring · emailRequired

Email address to set (provide empty string to remove email and disable notifications)

redirectstringOptional

Optional redirect URL for email confirmation flow

isCreditsWorkflowbooleanOptional

Whether this is part of the credits workflow (affects confirmation URL and email template)

Default: false

Responses

204

Email verification process initiated successfully (or email removed if empty string provided)

400

Invalid email format or email already registered to another account or domain blacklisted

application/json

401

Unauthorized - invalid or missing signed fetch headers

application/json

403

Forbidden - signed fetch metadata validation failed

application/json

put

/set-email

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

{
  "email": "[email protected]",
  "isCreditsWorkflow": false
}

No content

Confirm email address

put

/confirm-email

Confirms an email address using the verification code sent via email. Validates the code against the stored unconfirmed email entry. If Turnstile verification is enabled, also validates the captcha token. Upon success, moves the email to the confirmed subscriptions table and deletes the unconfirmed entry.

Body

addressstringRequired

Ethereum address of the user confirming the email

Pattern: ^0x[a-fA-F0-9]{40}$

codestring · min: 32 · max: 32Required

32-character verification code sent via email

turnstileTokenstringOptional

Cloudflare Turnstile captcha token (required when Turnstile verification is enabled)

sourcestring · enumOptional

Source of the email confirmation (used for analytics)

Possible values:

Responses

204

Email confirmed successfully

400

Invalid or missing confirmation code, address, or email domain blacklisted

application/json

401

Invalid captcha token (when Turnstile verification is enabled)

application/json

put

/confirm-email

PUT /confirm-email HTTP/1.1
Host: notifications.decentraland.org
Content-Type: application/json
Accept: */*
Content-Length: 117

{
  "address": "0xb5D7D1A05f553b5098D9274Df6B292e4e8222314",
  "code": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "source": "account"
}

No content

Check notification opt-out status

get

/subscription/opt-outs/{scope}/{scopeId}

Returns whether the authenticated user has opted out from the provided scope and scope identifier. The user 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>

Path parameters

scopestring · enumRequired

Scope type for the opt-out

Possible values:

scopeIdstring · min: 1Required

Identifier scoped to the scope (e.g., community ID)

Responses

200

Notification opt-out status retrieved successfully

application/json

scopestring · enumRequired

Scope type targeted by the opt-out

Possible values:

scopeIdstringRequired

Identifier scoped to the scope (e.g., community ID)

optedOutbooleanRequired

Whether the authenticated user has opted out

401

Unauthorized - invalid or missing signed fetch headers

application/json

403

Forbidden - signed fetch metadata validation failed

application/json

get

/subscription/opt-outs/{scope}/{scopeId}

GET /subscription/opt-outs/{scope}/{scopeId} HTTP/1.1
Host: notifications.decentraland.org
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "scope": "community",
  "scopeId": "text",
  "optedOut": true
}

Delete notification opt-out

delete

/subscription/opt-outs/{scope}/{scopeId}

Removes the opt-out configuration for the specified scope and scope identifier.

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>

Path parameters

scopestring · enumRequired

Scope type for the opt-out

Possible values:

scopeIdstring · min: 1Required

Identifier scoped to the scope (e.g., community ID)

Responses

204

Notification opt-out deleted successfully

401

Unauthorized - invalid or missing signed fetch headers

application/json

403

Forbidden - signed fetch metadata validation failed

application/json

delete

/subscription/opt-outs/{scope}/{scopeId}

DELETE /subscription/opt-outs/{scope}/{scopeId} HTTP/1.1
Host: notifications.decentraland.org
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Create notification opt-out

post

/subscription/opt-outs

Creates an opt-out configuration for the authenticated user based on a scope and scope identifier pair. Each scope maps to a canonical metadata configuration that determines which notifications are filtered.

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

scopestring · enumRequired

Scope type to opt out from

Possible values:

scopeIdstring · min: 1Required

Identifier scoped to the scope (e.g., community ID)

Responses

201

Notification opt-out created successfully

application/json

400

Invalid request - validation error

application/json

401

Unauthorized - invalid or missing signed fetch headers

application/json

403

Forbidden - signed fetch metadata validation failed

application/json

post

/subscription/opt-outs

POST /subscription/opt-outs HTTP/1.1
Host: notifications.decentraland.org
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 38

{
  "scope": "community",
  "scopeId": "text"
}

{
  "scope": "community",
  "scopeId": "text",
  "optedOut": true
}

PreviousNotifications NextPublishing

Last updated 4 months ago

hashtagGet user subscription preferences

hashtagUpdate subscription preferences

hashtagUnsubscribe from all email notifications

hashtagUnsubscribe from specific notification type

hashtagSet or update email address

hashtagConfirm email address

hashtagCheck notification opt-out status

hashtagDelete notification opt-out

hashtagCreate notification opt-out

Get user subscription preferences

Update subscription preferences

Unsubscribe from all email notifications

Unsubscribe from specific notification type

Set or update email address

Confirm email address

Check notification opt-out status

Delete notification opt-out

Create notification opt-out