prepareEmailCampaign

This method prepares a bulk email campaign by creating a bulk request that groups multiple protected data items. The prepared campaign request can then be sent using the sendEmailCampaign method.

INFO

This method is part of a two-step bulk campaign process:

1. Prepare the campaign using prepareEmailCampaign to create a bulk request
2. Send the campaign using sendEmailCampaign to process the bulk request

Usage

Browser

import { IExecWeb3mail } from '@iexec/web3mail';

const web3Provider = window.ethereum;
const web3mail = new IExecWeb3mail(web3Provider);

// Fetch contacts with bulk access
const contacts = await web3mail.fetchMyContacts({ bulkOnly: true });
const grantedAccessArray = contacts.map((contact) => contact.grantedAccess);

// Prepare the campaign
const emailCampaign = await web3mail.prepareEmailCampaign({
  grantedAccesses: grantedAccessArray,
  emailSubject: 'My email subject',
  emailContent: 'My email content',
  contentType: 'text/plain',
});

NodeJS

import { IExecWeb3mail, getWeb3Provider } from '@iexec/web3mail';

const web3Provider = getWeb3Provider('PRIVATE_KEY');
const web3mail = new IExecWeb3mail(web3Provider);

// Fetch contacts with bulk access
const contacts = await web3mail.fetchMyContacts({ bulkOnly: true });
const grantedAccessArray = contacts.map((contact) => contact.grantedAccess);

// Prepare the campaign
const emailCampaign = await web3mail.prepareEmailCampaign({
  grantedAccesses: grantedAccessArray,
  emailSubject: 'My email subject',
  emailContent: 'My email content',
  contentType: 'text/plain',
});

Parameters

import { type PrepareEmailCampaignParams } from '@iexec/web3mail';

grantedAccesses Required *

Type: GrantedAccess[]

An array of GrantedAccess objects representing contacts who have granted you access to their protected data with bulk processing capability.

const emailCampaign = await web3mail.prepareEmailCampaign({
  grantedAccesses: grantedAccessArray, 
  emailSubject: 'My subject',
  emailContent: 'My content',
});

emailSubject Required *

Type: string

The email subject that will be sent to all recipients.

const emailCampaign = await web3mail.prepareEmailCampaign({
  grantedAccesses: grantedAccessArray,
  emailSubject: 'My email subject', 
  emailContent: 'My email content',
});

emailContent Required *

Type: string

Maximum size: 512 kb

The email content that will be sent to all recipients. The content is encrypted and stored in IPFS.

const emailCampaign = await web3mail.prepareEmailCampaign({
  grantedAccesses: grantedAccessArray,
  emailSubject: 'My email subject',
  emailContent: 'My email content', 
});

contentType Optional

Type: string | undefined

Default: 'text/plain'

The MIME type of the email content (e.g., 'text/plain', 'text/html').

const emailCampaign = await web3mail.prepareEmailCampaign({
  grantedAccesses: grantedAccessArray,
  emailSubject: 'My email subject',
  emailContent: 'My email content',
  contentType: 'text/html', 
});

maxProtectedDataPerTask Optional

Type: number | undefined

Default: 100

Limits the number of protected data items processed per task.

const emailCampaign = await web3mail.prepareEmailCampaign({
  grantedAccesses: grantedAccessArray,
  emailSubject: 'My email subject',
  emailContent: 'My email content',
  maxProtectedDataPerTask: 10, 
});

workerpoolAddressOrEns Optional

Type: AddressOrENS | undefined

Default: Default workerpool from chain configuration

The workerpool address or ENS name that will execute the bulk campaign tasks. You can specify this during preparation or when sending the campaign.

const emailCampaign = await web3mail.prepareEmailCampaign({
  grantedAccesses: grantedAccessArray,
  emailSubject: 'My email subject',
  emailContent: 'My email content',
  workerpoolAddressOrEns: '0xa5de76...', 
});

workerpoolMaxPrice Optional

Type: number | undefined

Default: 0

The maximum amount (in nRLC) you are willing to pay the workerpool provider for using their infrastructure to run the Web3Mail app. You can specify this during preparation or when sending the campaign.

const emailCampaign = await web3mail.prepareEmailCampaign({
  grantedAccesses: grantedAccessArray,
  emailSubject: 'My email subject',
  emailContent: 'My email content',
  workerpoolMaxPrice: 0.1 * 1e9, 
});

label Optional

Type: string | undefined

An optional label to identify or categorize the campaign.

const emailCampaign = await web3mail.prepareEmailCampaign({
  grantedAccesses: grantedAccessArray,
  emailSubject: 'My email subject',
  emailContent: 'My email content',
  label: 'Newsletter Campaign', 
});

dataMaxPrice Optional

Type: number | undefined

Default: 0

The maximum amount (in nRLC) you are willing to pay for accessing the protected data.

const emailCampaign = await web3mail.prepareEmailCampaign({
  grantedAccesses: grantedAccessArray,
  emailSubject: 'My email subject',
  emailContent: 'My email content',
  dataMaxPrice: 0.1 * 1e9, 
});

appMaxPrice Optional

Type: number | undefined

Default: 0

The maximum amount (in nRLC) you are willing to pay the Web3Mail app provider for using the Web3Mail application.

const emailCampaign = await web3mail.prepareEmailCampaign({
  grantedAccesses: grantedAccessArray,
  emailSubject: 'My email subject',
  emailContent: 'My email content',
  appMaxPrice: 0.1 * 1e9, 
});

Return Value

import { type PrepareEmailCampaignResponse } from '@iexec/web3mail';

campaignRequest

Type: BulkRequest

The prepared bulk request object that contains all the necessary information to process the bulk campaign. This object should be passed to sendEmailCampaign to execute the campaign.

const { tasks } = await web3mail.sendEmailCampaign({
  campaignRequest: emailCampaign.campaignRequest, 
});

Related Documentation

• sendEmailCampaign Method - Send a prepared bulk campaign