[PB-5714] Add mail API to the sdk #358

TamaraFinogina · 2026-01-19T14:33:06Z

This PR adds functions needed for implementing Mail

larryrider · 2026-01-21T17:37:21Z

src/mail/index.ts

+      clientName: this.appDetails.clientName,
+      clientVersion: this.appDetails.clientVersion,
+      token: this.apiSecurity.token,
+      workspaceToken: this.apiSecurity.workspaceToken,


Is the workspaceToken or the desktopToken going to be needed for the meet server api?
If not, maybe its better to remove them from here 🤔

You are right, I took this part from drive I think

nope, copied headersWithToken from meet

maybe they should be removed from there too haha

@larryrider Fixed

larryrider · 2026-01-22T09:26:47Z

If you are going to do a new release, remember to update the package.json version

sg-gs · 2026-01-22T14:16:44Z

src/mail/index.ts

+   */
+  async decryptEmail(email: HybridEncryptedEmail, keys: EmailKeys): Promise<Email> {
+    const senderEmail = email.params.sender.email;
+    const pk = await this.getUserPublicKeys(senderEmail);


What is pk and why it contains the publicKeys while other object (keys) contains the private ones? I feel this confusing unless the pk name is clearer

pk is the public key of the sender. To decrypt the email, we need both the public key of the person who sent the email and the private key of the receiver. I can rename pk to senderPublicKeys

sg-gs · 2026-01-22T14:18:43Z

src/mail/index.ts

+   */
+  async getPublicKeysOfSeveralUsers(emails: string[]): Promise<UserWithPublicKeys[]> {
+    const response = await this.client.getWithParams<{ publicKeys: PublicKeysBase64; user: User }[]>(
+      `${this.apiUrl}/getPublicKeysOfSeveralUsers`,


This path is not following REST. Something like /users/keys with a body would be better

sg-gs · 2026-01-22T14:18:49Z

src/mail/index.ts

+   */
+  async getUserPublicKeys(userEmail: string): Promise<UserWithPublicKeys> {
+    const response = await this.client.getWithParams<{ publicKeys: PublicKeysBase64; user: User }>(
+      `${this.apiUrl}/getUserPublicKeys`,


sg-gs · 2026-01-22T14:19:34Z

src/mail/index.ts

+   * @returns Server response
+   */
+  async uploadKeystoreToServer(encryptedKeystore: EncryptedKeystore): Promise<void> {
+    return this.client.post(`${this.apiUrl}/uploadKeystore`, { encryptedKeystore }, this.headers());


And here:

POST /keys

Would be better

sg-gs · 2026-01-22T14:20:05Z

src/mail/index.ts

+   * @returns Server response
+   */
+  async sendEncryptedEmail(email: HybridEncryptedEmail): Promise<void> {
+    return this.client.post(`${this.apiUrl}/sendEncryptedEmail`, { email }, this.headers());


Same here

POST /mails

Would be more correct

sg-gs · 2026-01-22T14:20:17Z

src/mail/index.ts

+   * @returns Server response
+   */
+  async sendEncryptedEmailToMultipleRecipients(emails: HybridEncryptedEmail[]): Promise<void> {
+    return this.client.post(`${this.apiUrl}/sendEncryptedEmailToMultipleRecipients`, { emails }, this.headers());


sg-gs · 2026-01-22T14:20:35Z

src/mail/index.ts

+   * @returns Server response
+   */
+  async sendPwdProtectedEmail(email: PwdProtectedEmail): Promise<void> {
+    return this.client.post(`${this.apiUrl}/sendPwdProtectedEmail`, { email }, this.headers());


sg-gs · 2026-01-22T14:21:01Z

src/mail/index.ts

+   * @returns The encrypted keystore
+   */
+  async downloadKeystoreFromServer(userEmail: string, keystoreType: KeystoreType): Promise<EncryptedKeystore> {
+    return this.client.getWithParams(`${this.apiUrl}/getKeystore`, { userEmail, keystoreType }, this.headers());


Same here

GET /keys

TamaraFinogina · 2026-01-22T17:09:49Z

@sg-gs I've changed the paths, now they are:

uploadKeystoreToServer → /keystore
downloadKeystoreFromServer → /user/keystore
getUserWithPublicKeys → /user/public-keys
getSeveralUsersWithPublicKeys → /users/public-keys
sendEncryptedEmail → /email/encrypted
sendEncryptedEmailToMultipleRecipients → /emails/encrypted
sendPasswordProtectedEmail → /email/password-protected

I've used public-keys instead of keys because there are also private keys, and it might be confusing
The email can be encrypted with Kyber + ECC or protected with a shared password, which results in different encrypted email types (HybridEncryptedEmail and PwdProtectedEmail) - hence 2 different post methods
The email can be encrypted for several recipients, in which case the encrypted emails HybridEncryptedEmail are different for each recipient because recipientEmail and encryptedKey will be different based on who the exact recipient is, the rest of the HybridEncryptedEmail will be the same. I can adjust the type if necessary

 `HybridEncryptedEmail = {
    encryptedKey: HybridEncKey;
    enc: EmailBodyEncrypted;
    recipientEmail: string;
    params: EmailPublicParameters;
    id: string;
    isSubjectEncrypted: boolean;
}

sg-gs · 2026-01-23T11:41:42Z

@sg-gs I've changed the paths, now they are:

uploadKeystoreToServer → /keystore

downloadKeystoreFromServer → /user/keystore

getUserWithPublicKeys → /user/public-keys

getSeveralUsersWithPublicKeys → /users/public-keys

sendEncryptedEmail → /email/encrypted

sendEncryptedEmailToMultipleRecipients → /emails/encrypted

sendPasswordProtectedEmail → /email/password-protected

I've used public-keys instead of keys because there are also private keys, and it might be confusing

The email can be encrypted with Kyber + ECC or protected with a shared password, which results in different encrypted email types (HybridEncryptedEmail and PwdProtectedEmail) - hence 2 different post methods

The email can be encrypted for several recipients, in which case the encrypted emails HybridEncryptedEmail are different for each recipient because recipientEmail and encryptedKey will be different based on who the exact recipient is, the rest of the HybridEncryptedEmail will be the same. I can adjust the type if necessary
 `HybridEncryptedEmail = {
    encryptedKey: HybridEncKey;
    enc: EmailBodyEncrypted;
    recipientEmail: string;
    params: EmailPublicParameters;
    id: string;
    isSubjectEncrypted: boolean;
}

@TamaraFinogina
I see some potential improvements on the paths like entities should be always in plural and the duplication of EPs that should be under the same path. Thus I suggest you the following routes which I am pretty sure @jzunigax2 will almost agree:

uploadKeystoreToServer → POST /keystore
downloadKeystoreFromServer → GET /keystore
getUserWithPublicKeys → GET /users/public-keys?emails=<one_email_or_more>
getSeveralUsersWithPublicKeys → idem ⬆️
sendEncryptedEmail → POST /emails
sendEncryptedEmailToMultipleRecipients → idem ⬆️ (but different body)
sendPasswordProtectedEmail → idem ⬆️ (but different body)

Idea: Same action but additional params → same route (generally)

jzunigax2 · 2026-01-23T12:43:12Z

@sg-gs I've changed the paths, now they are:

uploadKeystoreToServer → /keystore

downloadKeystoreFromServer → /user/keystore

getUserWithPublicKeys → /user/public-keys

getSeveralUsersWithPublicKeys → /users/public-keys

sendEncryptedEmail → /email/encrypted

sendEncryptedEmailToMultipleRecipients → /emails/encrypted

sendPasswordProtectedEmail → /email/password-protected

I've used public-keys instead of keys because there are also private keys, and it might be confusing

The email can be encrypted with Kyber + ECC or protected with a shared password, which results in different encrypted email types (HybridEncryptedEmail and PwdProtectedEmail) - hence 2 different post methods

The email can be encrypted for several recipients, in which case the encrypted emails HybridEncryptedEmail are different for each recipient because recipientEmail and encryptedKey will be different based on who the exact recipient is, the rest of the HybridEncryptedEmail will be the same. I can adjust the type if necessary
 `HybridEncryptedEmail = {
    encryptedKey: HybridEncKey;
    enc: EmailBodyEncrypted;
    recipientEmail: string;
    params: EmailPublicParameters;
    id: string;
    isSubjectEncrypted: boolean;
}
@TamaraFinogina I see some potential improvements on the paths like entities should be always in plural and the duplication of EPs that should be under the same path. Thus I suggest you the following routes which I am pretty sure @jzunigax2 will almost agree:
* uploadKeystoreToServer → POST /keystore

* downloadKeystoreFromServer → GET /keystore

* getUserWithPublicKeys → GET /users/public-keys?emails=<one_email_or_more>

* getSeveralUsersWithPublicKeys → idem ⬆️

* sendEncryptedEmail → POST /emails

* sendEncryptedEmailToMultipleRecipients → idem ⬆️ (but different body)

* sendPasswordProtectedEmail → idem ⬆️ (but different body)
Idea: Same action but additional params → same route (generally)

yeah agreed, only the get keys requests seem like a POST to me, so we avoid sending the emails in query params as I know there is a max url limit (though I have no clue how big or small this limit is) or avoid possiby exposing recipients in a server request log

TamaraFinogina · 2026-01-23T16:00:15Z

@sg-gs @jzunigax2, functions now are the following:

uploadKeystoreToServer → /keystore
downloadKeystoreFromServer → /user/keystore
getUserWithPublicKeys →/users/public-keys with parameter emails: [userEmail]
getSeveralUsersWithPublicKeys → /users/public-keys with parameter emails
sendEncryptedEmail → /emails with parameter emails: [encryptedEmail]
sendEncryptedEmailToMultipleRecipients → /emails with parameter emails
sendPasswordProtectedEmail → /emails with parameter email

All of them are currently POST because getSeveralUsersWithPublicKeys and downloadKeystoreFromServer have user emails/email as parameters. I'm not sure we should expose them as part of the URL

P.S. I'm not sure if sendPasswordProtectedEmail should have emails, email, or something like pwd-email as input

TamaraFinogina added 2 commits January 19, 2026 12:02

first working tests

2229ca6

add more functions

2410545

TamaraFinogina requested review from CandelR, larryrider and xabg2 January 19, 2026 14:33

TamaraFinogina added 2 commits January 20, 2026 18:53

add more tests

01d9e17

add more tests

e0acf24

TamaraFinogina marked this pull request as ready for review January 21, 2026 17:24

TamaraFinogina requested a review from sg-gs January 21, 2026 17:25

larryrider reviewed Jan 21, 2026

View reviewed changes

remove workspace token, add tests for email decryption

20dde84

larryrider approved these changes Jan 22, 2026

View reviewed changes

up the sdk version in package.json

c0fbeb1

TamaraFinogina mentioned this pull request Jan 22, 2026

[PB-5714] Remove keystore api internxt/crypto#25

Open

7 tasks

sg-gs requested changes Jan 22, 2026

View reviewed changes

fix names and use REST pathes

f541cce

TamaraFinogina requested a review from sg-gs January 22, 2026 17:10

use plural names for endpoints, combine multiple endpoints in one

1f4f52d

[PB-5714] Add mail API to the sdk #358

Are you sure you want to change the base?

[PB-5714] Add mail API to the sdk #358

Conversation

TamaraFinogina commented Jan 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

larryrider commented Jan 22, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TamaraFinogina commented Jan 22, 2026

Uh oh!

sg-gs commented Jan 23, 2026

Uh oh!

jzunigax2 commented Jan 23, 2026

Uh oh!

TamaraFinogina commented Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants