The Hub user APIs provide tools for sending and receiving messages between Hub users. Mailboxes are built on ThreadDB.
User Mailboxes provide an encrypted endpoint where encrypted messages can be left for users while they're offline. User mailboxes are designed to be used with private key based identities where each user will privately encrypt messages for recipients based on the recipient's public key.
You can read more about creating basic PKI identities in our tutorial.
A common challenge app developers face is how to exchange small, private information from one user to another. Take for example, using Threads to handle chat messages between users.
Chat is a great use for Threads but faces an initial challenge:
How do you send Thread invite details from one user to another, before the thread exists?
Mailboxes allow one user of your app to encrypt and leave private messages or data for another user. Mailboxes are always online, so the user creating the message can do it immediately and the recipient can find it the next time they use your app.
To send messages, the sender only needs to know the recipient's public key and to be able to encrypt their message with that public key.
- Your app creates a new user using their identity and your Hub API key.
- Your app user authors a new message for a contact, based on the remote contact's public key.
- Your app user encrypts the message using the remote user's public key (encryption is handled by the Hub library).
- Your app sends the message to the remote user's inbox
To receive messages, a user simply needs to check their inbox and decrypt any messages using their private key.
- Your app user checks their Hub inbox using your API key.
- Your user can pull any available messages (by recency or other simple filters).
- Any message body will be encrypted, so decrypting the message using their private key is required.
- The user can then read and verify that the message came from the recipient.
A user's mailbox needs to be initialized by them (through your app) before other users can begin sending them messages.
Using inboxes and sentboxes¶
After a mailbox is set up, you can add the following methods to your application:
Message encryption and signing¶
Messages are encrypted using the recipient's ed2559 public key, meaning that the body of the message can only be read by the private key holder.
Read more about the identity utilities in the identity tutorial.
Some methods you will find useful include: