[PB-5714] Add mail API to the sdk by TamaraFinogina · Pull Request #358 · internxt/sdk

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

src/mail/index.ts

CandelR · 2026-02-17T16:03:39Z

src/mail/index.ts

+    const singleResponse = response[0];
+    const publicKeys = await base64ToPublicKey(singleResponse.publicKeys);


singleResponse.publicKeys will throw if the server returns an empty array
Consider adding a guard:
if (!response[0]) throw new Error(No public keys found for ${userEmail});

Done, check is added

CandelR · 2026-02-17T16:08:28Z

package.json

-    "uuid": "13.0.0"
+    "uuid": "13.0.0",
+    "internxt-crypto": "https://github.com/internxt/crypto/releases/download/v.0.0.12/internxt-crypto-0.0.12.tgz"
+


Need to create a task to release this package to npm

Yes, I'm preparing the release

Done, it uses version 0.0.13 now

sg-gs · 2026-02-19T11:46:20Z

test/mail/index.test.ts

+      ]);
+    });
+
+    it('should successfully create and upload a keystore', async () => {


Use when-then

something like:

'When a keystore upload is requested, then it should successfully upload the keystore.'?

@sg-gs Done

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

Merged

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

TamaraFinogina requested review from jzunigax2 and removed request for xabg2 February 17, 2026 09:57

TamaraFinogina added 4 commits February 17, 2026 11:12

merge master, update tests

fb06fbb

rename tests to .ts, remove .mts config

2a1707b

revert changes to auth

87f85dd

add internxt-crypto

d7c74ce

jzunigax2 requested changes Feb 17, 2026

View reviewed changes

src/mail/index.ts Outdated Show resolved Hide resolved

src/mail/index.ts Outdated Show resolved Hide resolved

src/mail/index.ts Outdated Show resolved Hide resolved

fix comments

051ff73

TamaraFinogina requested a review from jzunigax2 February 17, 2026 13:27

CandelR reviewed Feb 17, 2026

View reviewed changes

TamaraFinogina added 2 commits February 18, 2026 10:21

add null check

e14f68f

up the sdk version

2fbc2a9

CandelR approved these changes Feb 18, 2026

View reviewed changes

use released internxt-crypto

a57da0e

sg-gs reviewed Feb 19, 2026

View reviewed changes

change to when/then

a241333

TamaraFinogina requested a review from sg-gs February 19, 2026 14:46

sg-gs approved these changes Feb 19, 2026

View reviewed changes

jzunigax2 approved these changes Feb 19, 2026

View reviewed changes

TamaraFinogina merged commit 9d7fea7 into master Feb 19, 2026
1 check passed

TamaraFinogina deleted the add_mail_api branch February 19, 2026 15:22

		const singleResponse = response[0];
		const publicKeys = await base64ToPublicKey(singleResponse.publicKeys);

Comments

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!

Uh oh!

Uh oh!

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 Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

TamaraFinogina Feb 19, 2026 •

edited

Loading