Messaging API (1.0.0)

Feature Overview

The Messaging API is responsible for messaging interactions related to email, Push Protocol or XMTP.

Authenticated endpoint overview

This API uses signed messages to validate a given wallet is authorized to submit the request. Authentication headers must be provided using the approach described below.

How to authenticate

  • Determine the message that must be signed through the message generator endpoint
    • Request GET /api/user/{domain}/signature?device=true&expiry={timestamp}
      • Replace '{domain}' with desired domain
      • Replace '{expiry}' with desired Unix epoch timestamp
    • Response contains the message that must be signed
      • Message is a unique hash value
      • Represents combination of provided request parameters
      • Includes an expiration timestamp
  • User must sign the message returned by the message generator API
    • For example, the Metamask wallet could be used to sign the message
    • Generated signature is used in header of subsequent GET or POST request
  • Construct a request to the desired endpoint that requires user authentication
    • Must include headers
      • x-auth-domain - Must equal the {domain} in context
      • x-auth-expiration - Must equal the {expiry} timestamp in the signed message
      • x-auth-signature - Must be set to the value of the user generated signature

Communities

Creates a new Push Protocol token gated group

Creates a new Push Protocol token gated group if it does not yet exists. The group is associated with an Unstoppable Domains badge.

Request
Request Body schema: application/json
badgeCode
string

Badge code associated with the token gated group

Responses
200

Group created successfully

404

Badge not found

post/push/group
Request samples
application/json
{
  • "badgeCode": 123
}

Request to join a Push Protocol token gated community

Request to join a token gated community for a given wallet address. The request is granted if the token gating requirements are satisfied.

Request
Request Body schema: application/json
address
string

Wallet address to join the token gated group

badgeCode
string

Badge code associated with the token gated group

signature
string

Signature of the badge code created with user's Push Protocol private key

Responses
200

Group joined successfully

403

Wallet not authorized to join group

404

Group not found

post/push/group/join
Request samples
application/json
{
  • "address": 291,
  • "badgeCode": 123,
  • "signature": 291
}

Request to leave a Push Protocol token gated community

Request to leave a token gated community for a given wallet address.

Request
Request Body schema: application/json
address
string

Wallet address to join the token gated group

badgeCode
string

Badge code associated with the token gated group

signature
string

Signature of the badge code created with user's Push Protocol private key

Responses
200

Group was left successfully

404

Group not found

post/push/group/leave
Request samples
application/json
{
  • "address": 291,
  • "badgeCode": 123,
  • "signature": 291
}

Partner notifications

Send a message to holders of a badge

Allows an authorized user to send a message to all holders of a badge that have opted-in to partner notifications

Request
header Parameters
x-auth-domain
required
string

The domain to authorize. Should match the domain specified in the body

Example: mydomain.tld
x-auth-expires
required
string

The expiration time of the signature

Example: 1765522015090
x-auth-signature
required
string

The signature generating using domain owner private key

Example: b62348775da58077591e2d20506371e8d94a5a83031f34b9ac85845d3463e73b0f0a500875830785c093515806e354cda6c217acab0fce5245d662eff4105f5e1c
Request Body schema: application/json
badgeCode
string

The badge identifier

subject
string

Notification subject

message
string

Notification message body

ctaUrl
string

Optional link the user can click for more information

imageUrl
string

Optional link to an image

object
Responses
200

Notification successful

403

Notification not authorized

404

Domain not found

post/push/notification/badge
Request samples
application/json
{}

Status

status probe

This route can be used to determine if the application service is alive

Responses
200

application is alive

get/api/status
Request samples 
Response samples 
application/json
{
  • "status": {
    }
}
Chat
Determine if an address is marked as source of spam
The provided address is cross referenced against algorithms to suggest whether it has generated spam messages


Responses 
200
Registration successful


get/xmtp/spam/{address}
Request samples 
Response samples 
application/json
{
  • "isSpam": true
}
Accept an XMTP chat request
New XMTP chats are not show in the Unstoppable Messaging inbox by default. After a topic is accepted by the user, it is shown in the default view.


Request 
Request Body schema: application/json
ownerAddress
string
Domain owner public wallet address


 
signedPublicKey
string
XMTP account public key


 
Array of objects (SerializedTopicPost) 
 
Responses 
200
Accept successful


403
Accept not authorized


404
Not found


post/xmtp/topics/accept
Request samples 
application/json
{
  • "ownerAddress": 123,
  • "signedPublicKey": 456,
  • "registrations": [
    ]
}
Block an XMTP conversation
Block the specified XMTP topics and report as spam


Request 
Request Body schema: application/json
ownerAddress
string
Domain owner public wallet address


 
signedPublicKey
string
XMTP account public key


 
Array of objects (SerializedTopicPost) 
 
Responses 
200
Accept successful


403
Accept not authorized


404
Not found


post/xmtp/topics/block
Request samples 
application/json
{
  • "ownerAddress": 123,
  • "signedPublicKey": 456,
  • "registrations": [
    ]
}
Register an XMTP topic for mobile push notifications
Handles registration of XMTP topics to associate with mobile device tokens to receive push notifications


Request 
Request Body schema: application/json
ownerAddress
string
Domain owner public wallet address


 
signedPublicKey
string
XMTP account public key


 
Array of objects (SerializedTopicPost) 
 
Responses 
200
Registration successful


403
Notification not authorized


404
Not found


post/xmtp/topics/register
Request samples 
application/json
{
  • "ownerAddress": 123,
  • "signedPublicKey": 456,
  • "registrations": [
    ]
}