What Properties the MassEmailMessage Class Exposes for Bulk Email Sending

According to the Salesforce MassEmailMessage Class Reference, key properties include: setTargetObjectIds() accepts an array of Contact, Lead, or Person Account IDs (up to 250 per call). setTemplateId() requires an email template ID—mass email requires templates with no custom body allowed. setWhatIds() optionally accepts related record IDs for template merge fields (must match targetObjectIds order). setSenderDisplayName() sets the display name shown as the sender. setReplyTo() sets the reply-to email address. setSaveAsActivity() logs the email as an Activity on recipient records.

What Sending Limits the Mass Email API Imposes on Bulk Operations

Mass Email API is subject to strict Salesforce email limits. The daily external limit is 5,000 mass emails per day to external recipients (organization-wide). Internal emails to users with valid Salesforce licenses are unlimited. Recipients per call are capped at 250 target object IDs per MassEmailMessage. Per-transaction, only 10 sendEmail() invocations are allowed per Apex transaction. Limits vary by Salesforce edition—some editions have lower thresholds.

How to Send a Basic Mass Email Using the MassEmailMessage Class

Simple Apex code for mass email:


// Query recipients
List contacts = [SELECT Id FROM Contact WHERE ...];

List contactIds = new List();

for (Contact c : contacts) {
    contactIds.add(c.Id);
}

// Create mass email
Messaging.MassEmailMessage email = new Messaging.MassEmailMessage();

email.setTargetObjectIds(contactIds);
email.setTemplateId(templateId);
email.setSaveAsActivity(true);

// Send
Messaging.sendEmail(new Messaging.MassEmailMessage[] { email });

How to Include Related Record Data in Mass Email Template Merge Fields

Include related record data in template merge fields:


List contactIds = new List();
List opportunityIds = new List();

for (Contact c : contacts) {

    contactIds.add(c.Id);
    opportunityIds.add(c.Account.Opportunity__c);

}

Messaging.MassEmailMessage email = new Messaging.MassEmailMessage();

email.setTargetObjectIds(contactIds);
email.setWhatIds(opportunityIds); // Must match order
email.setTemplateId(templateId);

Messaging.sendEmail(new Messaging.MassEmailMessage[] { email });

How to Use Batch Apex for Mass Email Campaigns Exceeding 250 Recipients

For mass email campaigns exceeding 250 recipients, use Batch Apex. Batch Apex breaks large jobs into manageable chunks that each receive fresh governor limits.


global class MassEmailBatch implements Database.Batchable {

    private Id templateId;

    global MassEmailBatch(Id tempId) {
        this.templateId = tempId;
    }

    global Database.QueryLocator start(Database.BatchableContext bc) {

        return Database.getQueryLocator(
            [SELECT Id FROM Contact WHERE ...]
        );
    }

    global void execute(Database.BatchableContext bc,
                        List scope) {

        List ids = new List();

        for (Contact c : scope) {
            ids.add(c.Id);
        }

        Messaging.MassEmailMessage email =
            new Messaging.MassEmailMessage();

        email.setTargetObjectIds(ids);
        email.setTemplateId(templateId);

        Messaging.sendEmail(
            new Messaging.MassEmailMessage[] { email }
        );
    }

    global void finish(Database.BatchableContext bc) { }
}

How to Properly Handle Mass Email Send Results and Errors in Apex

Always check SendEmailResult for failures:


Messaging.SendEmailResult[] results = Messaging.sendEmail(emails);

for (Messaging.SendEmailResult result : results) {

    if (!result.isSuccess()) {

        for (Messaging.SendEmailError error : result.getErrors()) {

            System.debug('Status Code: ' + error.getStatusCode());
            System.debug('Error: ' + error.getMessage());
            System.debug('Target ID: ' + error.getTargetObjectId());

        }
    }
}

How Mass Email API Compares to SingleEmailMessage for Different Use Cases

The two APIs serve different purposes. Recipients: MassEmailMessage sends to 250 Contacts/Leads per call; SingleEmailMessage sends to 100 per call to any email address. Content: MassEmailMessage requires templates; SingleEmailMessage supports custom body or templates. Attachments: MassEmailMessage does not support attachments; SingleEmailMessage does. Use Case: MassEmailMessage suits marketing campaigns to known records; SingleEmailMessage suits transactional and triggered emails.

Mass Email API Best Practices for Reliable Bulk Sending at Scale

Optimize your mass email implementation. Check Limits: Query Limits.getMassEmailInvocations() before sending to avoid hitting daily limits. Batch Appropriately: Use a batch size of 200–250 to maximize efficiency while staying under limits. Respect Preferences: Always honor unsubscribe preferences—the API does this automatically, but verify your queries. Log Activities: Set saveAsActivity(true) for email tracking and history. Test Templates: Verify templates render correctly with all merge fields before mass sending. Monitor Results: Track email metrics and delivery success rates.

What Limitations Make Native Mass Email API Insufficient for Large-Scale Operations

Understand API constraints. Strict Limits: 5,000 daily limit constrains email campaigns at scale. No Tracking: Native API doesn’t provide open rates or click tracking. Deliverability: Shared IPs affect email deliverability. No dedicated IP option. Template Only: Cannot customize email body dynamically. Record Types Only: Can only send to Contacts, Leads, Person Accounts—not arbitrary addresses.

How Mass Email API Integrates with Marketing Workflows and Automation

Mass Email API integrates with marketing workflows. Campaign Attribution: Link mass emails to email campaigns for tracking. Automation: Trigger mass sends from email automation using Scheduled Apex. Drip Campaigns: Build drip campaigns and email sequences with scheduled batch jobs. List Management: Use contact lists and reports as source queries for recipients.

Enhanced Mass Email Capabilities That Scale Beyond Native API Limits

For organizations needing mass email beyond API limits, MassMailer operates 100% native to Salesforce. Unlimited sending without daily limits. Complete email capabilities with email analytics, including open and click tracking. Use the email builder for professional templates with follow-up sequences.

Key Takeaways

  • Mass Email API uses MassEmailMessage class for bulk sends to Contacts, Leads, and Person Accounts
  • Limited to 5,000 external recipients daily and 250 per API call with required templates
  • Use Batch Apex to process large recipient lists while respecting governor limits
  • Native solutions extend capabilities beyond API limitations with tracking and unlimited sending

Ready to break free from Mass Email API constraints? Install MassMailer free and unlock unlimited native Salesforce email sending with dedicated IPs, built-in engagement tracking, and automated drip sequences—all without a single line of Apex code. Get best-in-class capabilities today →