feat: restructure Web3Mail documentation and add integration guide

.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',

index.md

@@ -22,10 +22,6 @@ monetization.
   📽  Use case demo
 </a>
 
-<a href="./overview/how-to-pay-for-web3mail" class="link-for-home">
-  🔧 &nbsp;How to pay for web3mail
-</a>
-
 ## Our tools
 
 <a href="./tools/dataProtector" class="link-for-home">

tools/web3mail/integration-guide.md

@@ -0,0 +1,120 @@
+---
+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.
+
+<!-- prettier-ignore -->
+```ts twoslash
+import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector';
+
+const web3Provider = getWeb3Provider('PRIVATE_KEY');
+const dataProtectorCore = new IExecDataProtectorCore(web3Provider);
+const protectedData = await dataProtectorCore.protectData({ // [!code focus:5]
+  data: {
+    email: 'example@gmail.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.
+
+<!-- prettier-ignore -->
+```ts twoslash
+import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector';
+
+const web3Provider = getWeb3Provider('PRIVATE_KEY');
+const dataProtectorCore = new IExecDataProtectorCore(web3Provider);
+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
+  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.
+
+<!-- prettier-ignore -->
+```ts twoslash
+import { IExecWeb3mail, getWeb3Provider } from '@iexec/web3mail';
+
+const web3Provider = getWeb3Provider('PRIVATE_KEY');
+const web3mail = new IExecWeb3mail(web3Provider);
+const sendEmail = await web3mail.sendEmail({ // [!code focus:7]
+  protectedData: '0x123abc...', // Protected email data address
+  emailSubject: 'My email subject', 
+  emailContent: 'My email content',
+  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).

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.
 
+<!-- prettier-ignore -->
 ```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.
 
+<!-- prettier-ignore -->
 ```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.
 
+<!-- prettier-ignore -->
 ```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',