Manage XMTP inboxes

With XMTP, a user can have one or more inboxes they use to access their messages. An inbox can have multiple wallet addresses associated with it. All messages associated with these addresses flow through the one inbox ID and are accessible in any XMTP app.

For an overview of inbox IDs and their future in XMTP, see Identity in XMTP.

The first time someone uses your app with a wallet address they've never used with any app built with XMTP, your app creates an inbox ID and installation ID associated with the wallet address. To do this, you create a client for their wallet address.

The client creates an inbox ID and installation ID associated with the wallet address. By default, this wallet address is designated as the recovery address. A recovery address will always have the same inbox ID and cannot be reassigned to a different inbox ID.

When you make subsequent calls to create a client for the same wallet address and a local database is not present, the client uses the same inbox ID, but creates a new installation ID.

You can enable a user to add multiple wallet addresses to their inbox. Added addresses use the same inbox ID and the installation ID of the installation used to add the address.

You can enable a user to remove a wallet address from their inbox. You cannot remove the recovery wallet address.

Add a wallet address to an inbox

await client.addAccount(walletToAdd)

Remove a wallet address from an inbox

await client.removeAccount(recoveryWallet, addressToRemove)

Revoke all other installations

You can revoke all installations other than the currently accessed installation.

For example, consider a user using this current installation:

When the user revokes all other installations, the action removes all installations other than the current installation:

await client.revokeAllOtherInstallations(recoveryWallet)

View the inbox state

Find an inboxId for an address:

const inboxId = await client.inboxIdFromAddress(address)

View the state of any inbox to see the addresses, installations, and other information associated with the inboxId.

const state = await client.inboxState(true)
const states = await client.inboxStates(true, [inboxId, inboxId])

InboxState
{
	recoveryAddress: string,
	addresses: string[],
	installations: string[],
	inboxId: string,
}

FAQ

What happens when a user removes a wallet address?

Consider an inbox with four associated wallet addresses:

If the user removes an address from the inbox, the address no longer has access to the inbox it was removed from.

The address can no longer be added to or used to access conversations in that inbox. If someone sends a message to the address, the message is not associated with the original inbox. If the user logs in to a new installation with the address, this will create a new inbox ID.

How is the recovery address used?

The recovery address and its signer can be used to sign transactions that remove addresses and revoke installations.

For example, Alix can give Bo access to their inbox so Bo can see their groups and conversations and respond for Alix.

If Alix decides they no longer want Bo have access to their inbox, Alix can use their recovery address signer to remove Bo.

However, while Bo has access to Alix's inbox, Bo cannot remove Alix from their own inbox because Bo does not have access to Alix's recovery address signer.

If a user created two inboxes using two wallet addresses, is there a way to combine the inboxes?

If a user logs in with wallet address 0x62EE...309c and creates inbox 1 and then logs in with wallet address 0xd0e4...DCe8 and creates inbox 2; there is no way to combine inbox 1 and 2.

You can add wallet address 0xd0e4...DCe8 to inbox 1, but both address 0x62EE...309c and 0xd0e4...DCe8 would then have access to inbox 1 only. Wallet address 0xd0e4...DCe8 would no longer be able to access inbox 2.

To help users avoid this state, ensure that your UX surfaces their ability to add multiple wallet addresses to a single inbox.

What happens if I remove a wallet address from an inbox ID and then initiate a client with the private key of the removed address?

The wallet address used to initiate a client should be matched to its original inbox ID.

You do have the ability to rotate inbox IDs if a user reaches the limit of 257 identity actions (adding, removing, or revoking addresses or installations). Hopefully, users won’t reach this limit, but if they do, inbox IDs have a nonce and can be created an infinite number of times.

However, anytime a new inbox ID is created for an address, the conversations and messages in any existing inbox ID associated with the address are lost.

I have multiple addresses associated with one inbox ID. If I log in with any one of these addresses, does it access that inbox ID, or does it create a new inbox ID?

The address accesses that inbox ID and does not create a new inbox ID.

For example, let's say that you create a client with an address 0x62EE...309c. Inbox ID 1 is generated from that address 0x62EE...309c.

If you then add a different address 0xd0e4...DCe8 to inbox ID 1, address 0xd0e4...DCe8 is also associated with that inbox ID 1.

If you then log into a new app installation with address 0xd0e4...DCe8, it accesses inbox ID 1 and does not create a new inbox ID.

Once address 0xd0e4...DCe8 has been associated with inbox ID 1, it can then be used to log into inbox ID 1 using a new app installation.

The inverse is also true. Let's say address 0xd0e4...DCe8 was previously used to create and log into inbox ID 2.

If address 0xd0e4...DCe8 is then added as an associated address to inbox ID 1, address 0xd0e4...DCe8 will no longer be able to log into inbox ID 2.

To enable the user of address 0xd0e4...DCe8 to log into inbox ID 2 again, you can use the recovery address for inbox ID 2 to add a different address to inbox ID 2 and have the user use that address access it.

If you are interested in providing this functionality in your app and want some guidance, post to Ideas and Improvements in the XMTP Community Forums.