From 38be9074ec7d4cd1815cc3ce004c5459eb220086 Mon Sep 17 00:00:00 2001 From: ErwanDecoster Date: Thu, 31 Jul 2025 11:20:14 +0200 Subject: [PATCH 1/3] feat: restructure Web3Mail documentation and add integration guide --- .vitepress/sidebar.ts | 15 ++- index.md | 4 - .../web3mail}/how-to-pay-for-web3mail.md | 0 tools/web3mail/integration-guide.md | 117 ++++++++++++++++++ 4 files changed, 128 insertions(+), 8 deletions(-) rename {overview => tools/web3mail}/how-to-pay-for-web3mail.md (100%) create mode 100644 tools/web3mail/integration-guide.md diff --git a/.vitepress/sidebar.ts b/.vitepress/sidebar.ts index a34d4691..959af935 100644 --- a/.vitepress/sidebar.ts +++ b/.vitepress/sidebar.ts @@ -53,10 +53,6 @@ export function getSidebar() { // text: '💰  Pricing Considerations', // link: '/overview/pricing-considerations', // }, - { - text: '🔧  How to Pay for Web3mail', - link: '/overview/how-to-pay-for-web3mail', - }, ], }, { @@ -349,6 +345,17 @@ export function getSidebar() { }, ], }, + { + text: 'Integration Guide', + link: '/tools/web3mail/integration-guide', + collapsed: true, + items: [ + { + text: 'How to Pay for Web3mail', + link: '/tools/web3mail/how-to-pay-for-web3mail', + }, + ], + }, { text: 'Advanced Configuration', link: '/tools/web3mail/advanced-configuration', diff --git a/index.md b/index.md index 7abe3788..f6457cb1 100644 --- a/index.md +++ b/index.md @@ -22,10 +22,6 @@ monetization. 📽  Use case demo - - 🔧  How to pay for web3mail - - ## Our tools diff --git a/overview/how-to-pay-for-web3mail.md b/tools/web3mail/how-to-pay-for-web3mail.md similarity index 100% rename from overview/how-to-pay-for-web3mail.md rename to tools/web3mail/how-to-pay-for-web3mail.md diff --git a/tools/web3mail/integration-guide.md b/tools/web3mail/integration-guide.md new file mode 100644 index 00000000..e50feec4 --- /dev/null +++ b/tools/web3mail/integration-guide.md @@ -0,0 +1,117 @@ +--- +description: + Integrate iExec Web3Mail to enable secure and private email communication via + blockchain-based access control, ensuring user privacy and decentralized email + control +--- + +# iExec Web3Mail Integration Guide + +## Overview + +Integrating **iExec Web3Mail** enables secure and private email communication +using blockchain-based access control. This allows users to send and receive +emails while maintaining full control over their data. + +The integration process consists of the following steps: + +1. **Get your user to protect their email address via the iExec Data Protector + SDK.** +2. **Create the protected data via the iExec Data Protector SDK.** +3. **Grant access via the Data Protector SDK to authorize users to send + emails.** +4. **Send emails securely using the Web3Mail SDK.** + +## 1. Get your users to protect their email address + +To enable messaging via Web3Mail, you need your users to protect their email +address using iExec's Data Protector. + +An **email address** is protected and encrypted using iExec's technology. This +ensures that it remains **encrypted and private**, so only **authorized +senders** can contact the user **without revealing their actual email address**. +By **protecting their email address with iExec**, users ensure that only +**authorized applications and users** can send them emails. + +### Steps: + +- Ask the user to protect their email address using the Data Protector SDK. +- The protected data address will be used as an identifier for sending emails. +- Users maintain full control over who can send them emails and can revoke + access at any time. + +::: tip + +- Once the email address is protected, all authorized senders can send emails + without knowing the actual email address. +- The recipient can revoke access at any time to stop receiving emails from + specific senders. + +::: + +## 2. Create the protected data with data protector SDK + +Your users need to protect their email address using iExec's Data Protector to +ensure privacy and security. + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +const protectedData = await dataProtectorCore.protectData({ + data: { + email: 'user@example.com', // User's email address + }, +}); +``` + +## 3. Grant access via data protector SDK + +To allow specific users or applications to send emails, you must explicitly +grant access. + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +const grantedAccess = await dataProtectorCore.grantAccess({ + protectedData: '0x123abc...', // Protected email data address + authorizedApp: '0x456def...', // Web3Mail app address + authorizedUser: '0x789cba...', // Ethereum address of the authorized sender + pricePerAccess: 3, // Cost per email (in iExec tokens) + numberOfAccess: 10, // Allowed email count + onStatusUpdate: ({ title, isDone }) => { + console.log(title, isDone); + }, +}); +``` + +## 4. Send emails via Web3Mail SDK + +Once authorized, a user can send emails via Web3Mail SDK. + +```ts twoslash +import { IExecWeb3mail, getWeb3Provider } from '@iexec/web3mail'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const web3mail = new IExecWeb3mail(web3Provider); +const sendEmail = await web3mail.sendEmail({ + protectedData: '0x123abc...', // Protected email data address + emailSubject: 'Hello from Web3Mail', + emailContent: 'This is a secure email sent via iExec Web3Mail', + senderName: 'Arthur', + contentType: 'text/html', // or 'text/plain' +}); +``` + +## Conclusion + +By integrating **iExec Web3Mail**, you ensure privacy, security, and +decentralized control over your email communication. Your users decide who can +send them emails and set a cost for access while keeping their email address +hidden. + +For further support, join the iExec community on +[Discord](https://discord.com/invite/pbt9m98wnU). From 2de9308282f4f8d46d597bc54cb700c2abd12665 Mon Sep 17 00:00:00 2001 From: ErwanDecoster Date: Thu, 31 Jul 2025 11:57:29 +0200 Subject: [PATCH 2/3] fix: update example email and message content in integration guide --- tools/web3mail/integration-guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tools/web3mail/integration-guide.md b/tools/web3mail/integration-guide.md index e50feec4..9e9f7d7d 100644 --- a/tools/web3mail/integration-guide.md +++ b/tools/web3mail/integration-guide.md @@ -61,7 +61,7 @@ const web3Provider = getWeb3Provider('PRIVATE_KEY'); const dataProtectorCore = new IExecDataProtectorCore(web3Provider); const protectedData = await dataProtectorCore.protectData({ data: { - email: 'user@example.com', // User's email address + email: 'example@gmail.com', // User's email address }, }); ``` @@ -99,8 +99,8 @@ const web3Provider = getWeb3Provider('PRIVATE_KEY'); const web3mail = new IExecWeb3mail(web3Provider); const sendEmail = await web3mail.sendEmail({ protectedData: '0x123abc...', // Protected email data address - emailSubject: 'Hello from Web3Mail', - emailContent: 'This is a secure email sent via iExec Web3Mail', + emailSubject: 'My email subject', + emailContent: 'My email content', senderName: 'Arthur', contentType: 'text/html', // or 'text/plain' }); From b7ba4642c9bfd6d4f9aec803660eed91d8a9c812 Mon Sep 17 00:00:00 2001 From: ErwanDecoster Date: Thu, 31 Jul 2025 14:42:04 +0200 Subject: [PATCH 3/3] fix: update integration guide with focus in code examples --- tools/web3mail/integration-guide.md | 13 ++++++++----- tools/web3telegram/integration-guide.md | 12 +++++++++--- 2 files changed, 17 insertions(+), 8 deletions(-) diff --git a/tools/web3mail/integration-guide.md b/tools/web3mail/integration-guide.md index 9e9f7d7d..6cc11827 100644 --- a/tools/web3mail/integration-guide.md +++ b/tools/web3mail/integration-guide.md @@ -54,12 +54,13 @@ By **protecting their email address with iExec**, users ensure that only Your users need to protect their email address using iExec's Data Protector to ensure privacy and security. + ```ts twoslash import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; const web3Provider = getWeb3Provider('PRIVATE_KEY'); const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -const protectedData = await dataProtectorCore.protectData({ +const protectedData = await dataProtectorCore.protectData({ // [!code focus:5] data: { email: 'example@gmail.com', // User's email address }, @@ -71,12 +72,13 @@ const protectedData = await dataProtectorCore.protectData({ To allow specific users or applications to send emails, you must explicitly grant access. + ```ts twoslash import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; const web3Provider = getWeb3Provider('PRIVATE_KEY'); const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -const grantedAccess = await dataProtectorCore.grantAccess({ +const grantedAccess = await dataProtectorCore.grantAccess({ // [!code focus:10] protectedData: '0x123abc...', // Protected email data address authorizedApp: '0x456def...', // Web3Mail app address authorizedUser: '0x789cba...', // Ethereum address of the authorized sender @@ -92,17 +94,18 @@ const grantedAccess = await dataProtectorCore.grantAccess({ Once authorized, a user can send emails via Web3Mail SDK. + ```ts twoslash import { IExecWeb3mail, getWeb3Provider } from '@iexec/web3mail'; const web3Provider = getWeb3Provider('PRIVATE_KEY'); const web3mail = new IExecWeb3mail(web3Provider); -const sendEmail = await web3mail.sendEmail({ +const sendEmail = await web3mail.sendEmail({ // [!code focus:7] protectedData: '0x123abc...', // Protected email data address - emailSubject: 'My email subject', + emailSubject: 'My email subject', emailContent: 'My email content', senderName: 'Arthur', - contentType: 'text/html', // or 'text/plain' + contentType: 'text/html', // or 'text/plain' }); ``` diff --git a/tools/web3telegram/integration-guide.md b/tools/web3telegram/integration-guide.md index b85a174e..8d276c18 100644 --- a/tools/web3telegram/integration-guide.md +++ b/tools/web3telegram/integration-guide.md @@ -53,11 +53,13 @@ senders** can contact you. After obtaining your user's Chat ID, you need to protect it using iExec’s Data Protector to ensure privacy and security. + ```ts twoslash import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + const web3Provider = getWeb3Provider('PRIVATE_KEY'); const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -const protectedData = await dataProtectorCore.protectData({ +const protectedData = await dataProtectorCore.protectData({// [!code focus:5] data: { telegram_chatId: '12345678', // Recipient's Chat ID }, @@ -69,11 +71,13 @@ const protectedData = await dataProtectorCore.protectData({ To allow users to send messages, you must explicitly grant access to specific users. + ```ts twoslash import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + const web3Provider = getWeb3Provider('PRIVATE_KEY'); const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -const grantedAccess = await dataProtectorCore.grantAccess({ +const grantedAccess = await dataProtectorCore.grantAccess({ // [!code focus:10] protectedData: '0x123abc...', // Protected Chat ID data address authorizedApp: '0x456def...', // Web3Telegram app address authorizedUser: '0x789cba...', // Ethereum address of the authorized sender @@ -89,11 +93,13 @@ const grantedAccess = await dataProtectorCore.grantAccess({ Once authorized, a user can send messages via Web3Telegram SDK. + ```ts twoslash import { IExecWeb3telegram, getWeb3Provider } from '@iexec/web3telegram'; + const web3Provider = getWeb3Provider('PRIVATE_KEY'); const web3telegram = new IExecWeb3telegram(web3Provider); -const sendTelegram = await web3telegram.sendTelegram({ +const sendTelegram = await web3telegram.sendTelegram({ // [!code focus:5] protectedData: '0x123abc...', // Protected Chat ID data address senderName: 'Arthur', telegramContent: 'My telegram message content',