User Mailboxes¶
Warning
We are shutting down our hosted Hub infrastructure. Please see this deprecation notice for details.
The Hub user APIs provide tools for sending and receiving messages between Hub users. Mailboxes are built on ThreadDB.
Visit the GoDoc or JavaScript Users doc for a complete list of methods and more usage descriptions.
Mailbox overview¶
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.
Info
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:
Challenge
How do you send Thread invite details from one user to another, before the thread exists?
Solution
User mailboxes!
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.
Sending messages¶
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
Receiving¶
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.
Creating mailboxes¶
A user's mailbox needs to be initialized by them (through your app) before other users can begin sending them messages.
We suggest you do this as part of the onboarding steps in your app. You can read about this creation process in Go and Javascript.
Using inboxes and sentboxes¶
After a mailbox is set up, you can add the following methods to your application:
- Get an existing mailbox. Golang, JavaScript.
- Send messages. Golang, JavaScript.
- Watch inbox. Golang, JavaScript.
And more!
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: