docs(web3mail,web3telegram): add bulk processing documentation

- Add prepareEmailCampaign and sendEmailCampaign methods for Web3Mail
- Add prepareTelegramCampaign and sendTelegramCampaign methods for Web3Telegram
- Integrate bulk processing content into integrate-web3-messaging guide
- Add bulkOnly parameter documentation to fetchMyContacts and fetchUserContacts
- Add allowBulk parameter explanation to grantAccess method

Author: abbesBenayache

.vitepress/sidebar.ts

@@ -317,6 +317,14 @@ export function getSidebar() {
                 text: 'sendEmail',
                 link: '/references/web3mail/methods/sendEmail',
               },
+              {
+                text: 'prepareEmailCampaign',
+                link: '/references/web3mail/methods/prepareEmailCampaign',
+              },
+              {
+                text: 'sendEmailCampaign',
+                link: '/references/web3mail/methods/sendEmailCampaign',
+              },
             ],
           },
           {
@@ -349,6 +357,14 @@ export function getSidebar() {
                 text: 'sendTelegram',
                 link: '/references/web3telegram/methods/sendTelegram',
               },
+              {
+                text: 'prepareTelegramCampaign',
+                link: '/references/web3telegram/methods/prepareTelegramCampaign',
+              },
+              {
+                text: 'sendTelegramCampaign',
+                link: '/references/web3telegram/methods/sendTelegramCampaign',
+              },
             ],
           },
 

src/guides/use-iapp/integrate-web3-messaging.md

@@ -71,7 +71,9 @@ const protectedData = await dataProtectorCore.protectData({
 
 Grant permission for a sender and/or an app to contact the user.
 
-```ts twoslash
+::: code-group
+
+```ts twoslash [Single Message]
 import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector';
 const web3Provider = getWeb3Provider('PRIVATE_KEY');
 const dataProtectorCore = new IExecDataProtectorCore(web3Provider);
@@ -85,11 +87,47 @@ const grantedAccess = await dataProtectorCore.grantAccess({
 });
 ```
 
+```ts twoslash [Bulk Campaigns]
+import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector';
+const web3Provider = getWeb3Provider('PRIVATE_KEY');
+const dataProtectorCore = new IExecDataProtectorCore(web3Provider);
+
+// For bulk campaigns, recipients must grant access with allowBulk: true
+const grantedAccess = await dataProtectorCore.grantAccess({
+  protectedData: '0x123abc...',
+  authorizedApp: '0x456def...',
+  authorizedUser: '0x789cba...',
+  allowBulk: true, // [!code focus] Enable bulk processing
+});
+```
+
+:::
+
+::: info
+
+Setting `allowBulk: true` automatically configures `pricePerAccess` to `0` and
+`numberOfAccess` to `Number.MAX_SAFE_INTEGER`, enabling unlimited bulk
+processing at no cost per access.
+
+:::
+
 ## 4. Send the Message
 
+You can send messages in two modes:
+
+- **Single Processing**: Send to one recipient using `sendEmail` or
+  `sendTelegram`
+- **Bulk Processing**: Send the same message to multiple recipients efficiently
+  using `prepareEmailCampaign` + `sendEmailCampaign` or
+  `prepareTelegramCampaign` + `sendTelegramCampaign`
+
+### Single Message Processing
+
+Send a message to a single recipient:
+
 ::: code-group
 
-```ts twoslash [Web3Mail]
+```ts twoslash [Web3Mail - Single]
 import { IExecWeb3mail, getWeb3Provider } from '@iexec/web3mail';
 
 const web3Provider = getWeb3Provider('PRIVATE_KEY');
@@ -99,11 +137,10 @@ const sendEmail = await web3mail.sendEmail({
   protectedData: '0x123abc...',
   emailSubject: 'My email subject',
   emailContent: 'My email content',
-  // useVoucher: true,
 });
 ```
 
-```ts twoslash [Web3Telegram]
+```ts twoslash [Web3Telegram - Single]
 import { IExecWeb3telegram, getWeb3Provider } from '@iexec/web3telegram';
 
 const web3Provider = getWeb3Provider('PRIVATE_KEY');
@@ -118,6 +155,88 @@ const sendTelegram = await web3telegram.sendTelegram({
 
 :::
 
+### Bulk Message Processing
+
+Send the same message to multiple recipients efficiently in a single
+transaction.
+
+**How it works:**
+
+1. **Fetch contacts** with bulk access capability using `fetchMyContacts` or
+   `fetchUserContacts` with `bulkOnly: true`
+2. **Prepare the campaign** using `prepareEmailCampaign` or
+   `prepareTelegramCampaign` to create a bulk request
+3. **Send the campaign** using `sendEmailCampaign` or `sendTelegramCampaign` to
+   process the bulk request
+
+::: warning Prerequisites
+
+Before using bulk processing, ensure that recipients have granted access with
+`allowBulk: true` when calling `grantAccess` (see step 3 above).
+
+:::
+
+::: code-group
+
+```ts twoslash [Web3Mail - Bulk]
+import { IExecWeb3mail, getWeb3Provider } from '@iexec/web3mail';
+
+const web3Provider = getWeb3Provider('PRIVATE_KEY');
+const web3mail = new IExecWeb3mail(web3Provider);
+
+// Step 1: Fetch contacts with bulk access
+const contacts = await web3mail.fetchMyContacts({ bulkOnly: true });
+const grantedAccessArray = contacts.map((contact) => contact.grantedAccess);
+
+// Step 2: Prepare the campaign
+const emailCampaign = await web3mail.prepareEmailCampaign({
+  grantedAccess: grantedAccessArray,
+  emailSubject: 'Hello from My Awesome App!',
+  emailContent: 'Hello! This is a bulk email sent to all recipients.',
+  contentType: 'text/html',
+});
+
+// Step 3: Send the bulk campaign
+const result = await web3mail.sendEmailCampaign({
+  campaignRequest: emailCampaign.campaignRequest,
+});
+
+console.log(`Campaign sent! Created ${result.tasks.length} tasks`);
+```
+
+```ts twoslash [Web3Telegram - Bulk]
+import { IExecWeb3telegram, getWeb3Provider } from '@iexec/web3telegram';
+
+const web3Provider = getWeb3Provider('PRIVATE_KEY');
+const web3telegram = new IExecWeb3telegram(web3Provider);
+
+// Step 1: Fetch contacts with bulk access
+const contacts = await web3telegram.fetchMyContacts({ bulkOnly: true });
+const grantedAccessArray = contacts.map((contact) => contact.grantedAccess);
+
+// Step 2: Prepare the campaign
+const telegramCampaign = await web3telegram.prepareTelegramCampaign({
+  grantedAccess: grantedAccessArray,
+  telegramContent: 'Hello! This is a bulk message sent to all recipients.',
+  senderName: 'My Awesome App',
+});
+
+// Step 3: Send the bulk campaign
+const result = await web3telegram.sendTelegramCampaign({
+  campaignRequest: telegramCampaign.campaignRequest,
+});
+
+console.log(`Campaign sent! Created ${result.tasks.length} tasks`);
+```
+
+:::
+
+**Benefits:**
+
+- Lower costs: fewer transactions reduce gas fees
+- Higher performance: multiple recipients processed in parallel
+- Better scalability: efficiently handle hundreds or thousands of recipients
+
 ## Payment
 
 Each message sent through Web3Mail or Web3Telegram requires payment in RLC

src/references/dataProtector/methods/grantAccess.md

@@ -206,6 +206,33 @@ const grantedAccess = await dataProtectorCore.grantAccess({
 });
 ```
 
+### allowBulk <OptionalBadge />
+
+**Type:** `boolean`
+
+**Default:** `false`
+
+When set to `true`, enables bulk processing for this access grant. This allows
+multiple protected data items to be processed together in a single task, which
+is more efficient for bulk operations like sending campaigns to multiple
+recipients.
+
+When `allowBulk: true` is set, the following parameters are automatically
+configured:
+
+- **Price per access**: Set to `0` (no price per access)
+- **Number of accesses**: Set to `Number.MAX_SAFE_INTEGER` (maximum number of
+  accesses)
+
+```ts twoslash
+const grantedAccess = await dataProtectorCore.grantAccess({
+  protectedData: '0x123abc...',
+  authorizedApp: '0x456def...',
+  authorizedUser: '0x789cba...',
+  allowBulk: true, // [!code focus] Enable bulk processing
+});
+```
+
 ### onStatusUpdate <OptionalBadge />
 
 **Type:** `OnStatusUpdateFn<GrantAccessStatuses>`

src/references/web3mail/methods/fetchMyContacts.md

@@ -54,6 +54,33 @@ const contactsList = await web3mail.fetchMyContacts({
 });
 ```
 
+### bulkOnly <OptionalBadge />
+
+**Type:** `boolean`
+
+**Default:** `false`
+
+When set to `true`, this parameter filters contacts to only return those who
+have granted access with bulk processing capability. These contacts can be used
+with [`prepareEmailCampaign`](/references/web3mail/methods/prepareEmailCampaign)
+and [`sendEmailCampaign`](/references/web3mail/methods/sendEmailCampaign) for
+bulk campaigns.
+
+::: warning
+
+To enable bulk processing, recipients must grant access with `allowBulk: true`
+when calling [`grantAccess`](/references/dataProtector/methods/grantAccess) on
+the Data Protector SDK.
+
+:::
+
+```ts twoslash
+// Fetch contacts with bulk access
+const bulkContacts = await web3mail.fetchMyContacts({
+  bulkOnly: true, // [!code focus]
+});
+```
+
 ## Return Value
 
 The result object contains a list of `contact` objects. Each `contact`
@@ -67,5 +94,5 @@ import { type Contact } from '@iexec/web3mail';
 [`Contact[]`](/references/dataProtector/types#contact)
 
 <script setup>
-import OptionalBadge from '@/components/OptionalBadge.vue'
+import OptionalBadge from '@/components/OptionalBadge.vue';
 </script>

src/references/web3mail/methods/fetchUserContacts.md

@@ -74,6 +74,33 @@ const contactsList = await web3mail.fetchUserContacts({
 });
 ```
 
+### bulkOnly <OptionalBadge />
+
+**Type:** `boolean`
+
+**Default:** `false`
+
+When set to `true`, this parameter filters contacts to only return those who
+have granted access with bulk processing capability. These contacts can be used
+with [`prepareEmailCampaign`](/references/web3mail/methods/prepareEmailCampaign)
+and [`sendEmailCampaign`](/references/web3mail/methods/sendEmailCampaign) for
+bulk campaigns.
+
+::: warning
+
+To enable bulk processing, recipients must grant access with `allowBulk: true`
+when calling [`grantAccess`](/references/dataProtector/methods/grantAccess) on
+the Data Protector SDK.
+
+:::
+
+```ts twoslash
+// Fetch contacts with bulk access for a specific user
+const bulkContacts = await web3mail.fetchUserContacts({
+  bulkOnly: true, // [!code focus]
+});
+```
+
 ## Return Value
 
 The result object contains a list of `contact` objects. Each `contact`
@@ -87,5 +114,6 @@ import { type Contact } from '@iexec/web3mail';
 [`Contract[]`](/references/dataProtector/types#contact)
 
 <script setup>
-import RequiredBadge from '@/components/RequiredBadge.vue'
+import RequiredBadge from '@/components/RequiredBadge.vue';
+import OptionalBadge from '@/components/OptionalBadge.vue';
 </script>