Clean Suite for CRM: Salesforce Reference Guide

Clean Suite for CRM: Salesforce Reference Guide#

Global Address Validation #

Single Record Processing #

Global Address Validation processes one Salesforce record through MD_GlobalAddressWSExt.

The package reads the input fields from a globalAddress Custom Mapping. It sends the package JSON envelope to Melissa. It saves the response in MD_globalAddressResult__c and applies configured output mappings.

See Package Request Envelope for the actual request format.

How to use Lightning Quick Action #

Before you use the action, add the package action to the active record page layout.

Open a record that has a Global Address Custom Mapping.
Start the configured Global Address quick action.
Wait for the package to process the record.
Review the configured output fields or MD_globalAddressResult__c.

Apex Use #

Use the synchronous method for one record.

String outcome = MDPERSONATOR.MD_GlobalAddressWSExt.doGlobalAddress(recordId);

The method returns Success after processing. It does not return Melissa result codes.

Read the configured result-code output field or MD_globalAddressResult__c.Results__c for the result codes.

Trigger Use #

Call doOneGlobalAddress(recordId) from trigger logic when the callout must run asynchronously. The method has @Future(callout=true) and returns no value.

Official Service Reference #

See Melissa Global Address Verification documentation for service behavior and result codes.

Batch Processing #

Clean Suite Batch Processing validates address data across large datasets asynchronously using Apex batch jobs.

Introduction #

Batch processing uses MD_GlobalBatch to process thousands of Salesforce records. The batch engine reads a SOQL query and groups records into batches of 100. It sends requests to Melissa Global Address services. It then writes standardized address fields and result codes to Salesforce records.

Batch Job Flow #

This flow shows how the batch job processes address records.

Diagram flow

SOQL query → Matching Salesforce records
Matching Salesforce records → Batches of 100 records
Batches of 100 records → MD_GlobalBatch
MD_GlobalBatch → Melissa Global Address service
Melissa Global Address service → Standardized fields and result codes
Standardized fields and result codes → Salesforce records

How to use the Clean Suite Batch interface #

Follow these steps to launch a batch job from the user interface:

Open the Clean Suite app from the App Launcher.
Click the Clean Suite Batch tab.
Select Global Address from the Engine dropdown list.
Select the target Salesforce Object (for example Contact or Lead).
Select an active Field Mapping.
(Optional) Enter a custom SOQL WHERE clause to filter records (for example MailingPostalCode = NULL).
Click Run Batch.
Monitor progress under Setup → Async Apex Jobs.

Advanced Batch Processing #

Exposed Methods #

Invoke batch jobs programmatically using MD_CleanSuiteBatchController:

public static Id executeBatchJob(
String Engine,              // 'MD_GlobalBatch'
String BatchObject,         // 'Contact', 'Lead', or custom object name
String Query,               // Full SOQL query string if CustomQuery is true
String Mapping,             // Custom mapping record Name
Boolean RecordUpdate,       // true to update target records with address results
Boolean ProcessAll,         // true to process all records regardless of prior verification
Boolean CustomQuery,        // true to use custom SOQL query
String SmartMoverListName,  // Unused for Global Address (pass empty string)
String SmartMoverJobId      // Unused for Global Address (pass empty string)

)

Sample Code #

Use this Apex code to launch a Global Address batch job from an admin script or Apex trigger:

// Define batch parameter values
String engine = 'MD_GlobalBatch';
String targetObject = 'Contact';
String customQuery = 'SELECT Id FROM Contact WHERE MailingCountry = \'US\' AND Clean_Suite_Global_Address_Result__c = NULL';
String mappingName = 'Contact Global Address Mapping';
Boolean updateRecords = true;
Boolean processAll = false;
Boolean isCustomQuery = true;

// Execute batch job
Id jobId = MDPERSONATOR.MD_CleanSuiteBatchController.executeBatchJob(
    engine,
    targetObject,
    customQuery,
    mappingName,
    updateRecords,
    processAll,
    isCustomQuery,
    '',
    ''
);

Best Practices #

Limit Batch Scope: Pass a SOQL WHERE clause to target unverified records only. This reduces API credit usage.
Batch Size Limit: Keep batch size at 100 records per chunk to match Melissa service payload limits.
Avoid Concurrent Batches: Do not run two Global Address batch jobs on the same object at the same time. Concurrent jobs can cause record lock conflicts.

Admin Configuration #

The package reads these configuration options from the latest MD_suiteSetting__c record named webServiceOptions. These options control address validation output and behavior.

UI Label	API Field	Allowed Values	Default	Effect
Country of Origin	`countryOfOrigin__c`	All ISO country codes (US, GB, CA, etc.)	`US`	Sets geographic context for address validation and output locale.
Output Script	`outputScript__c`	NOCHANGE, NATIVE, LATN	`NOCHANGE`	Controls character set conversion in output. NATIVE preserves the native script. LATN converts to Latin transliteration.
Geocode	`geocode__c`	GEOOFF, GEOON	`GEOON`	When GEOON, the service returns geocoordinates. When GEOOFF, geocoding is disabled.
Delivery Lines	`gavDeliveryLines__c`	On, Off	`Off`	When on, includes delivery point information in results.
Include Remnant	`gavIncludeRemnant__c`	On, Off	`On`	When on, includes remnant address lines (fragments that do not match known data).
Detailed Results	`gavDetailedResults__c`	On, Off	`Off`	When on, returns extended result detail in output.
Area Details	`gavAreaDetails__c`	On, Off	`Off`	When on, includes area-specific demographic and geographic details.
US Extras (Census, County, School)	`gavUSExtras__c`	On, Off	`Off`	When on, appends US census tract, county, and school district codes to results.
US Preferred City Names	`gavUSPreferredCityNames__c`	On, Off	`Off`	When on, the service returns USPS preferred city names instead of standard names.
Melissa City Keys	`gavMelissaCityKeys__c`	On, Off	`Off`	When on, includes Melissa Data proprietary city key identifier.
GB Extras (UPRN)	`gavGBExtras__c`	On, Off	`Off`	When on, UK addresses include Unique Property Reference Number (UPRN).
Extended Date/Time (UTC, DST)	`gavExtendedDateTime__c`	On, Off	`Off`	When on, the service returns UTC and daylight saving time information with geocoding results.
US Standardization Type	`gavUSStandardizationType__c`	Short, Long, Auto	`Short`	Controls US address format in output. Short represents two-letter state abbreviation. Long represents full state name. Auto lets the system decide based on address.
Line Separator	`gavLineSeparator__c`	SEMICOLON, PIPE, CR, LF, CRLF, TAB, BR	`SEMICOLON`	Specifies character used to separate multi-line address components in output.
Address Update Codes	`globalVerifyLevel__c`	Regex pattern strings (e.g., AV2[45])	`AV2[45]`	Specifies which Global Address result codes trigger record updates.

Result Codes #

Global Address Validation returns record-level codes for each verified address and service-level codes for request errors or warnings.

For the complete result-code reference, roadmap, and result-code routing guidance, see Result Codes.

Engineering Reference #

Exposed Methods #

MD_GlobalAddressWSExt.doGlobalAddress(Id recordId)#

Item	Value
Scope	`global static String`
Processing	Synchronous
Input	Salesforce record ID
Success return	Literal `Success`
Empty return	`''` when the initial object or result-object field-access check fails, or when no Custom Mapping exists for the record object.

The method does not return Melissa result codes. Read the configured result-code output field or MD_globalAddressResult__c.Results__c.

MD_GlobalAddressWSExt.doOneGlobalAddress(Id recordId)#

Item	Value
Scope	`global static void`
Processing	`@Future(callout=true)`
Input	Salesforce record ID
Return	No value

doOneGlobalAddress calls doGlobalAddress in an asynchronous transaction.

Synchronous Workflow #

Call doGlobalAddress with one Salesforce record ID.
The package checks object and result-object field access.
The package reads Custom Mappings for the record object.
The package sends each globalAddress mapping in the package JSON envelope.
The package saves response records and applies configured output mappings.

The package uses the mapping input entries for organization, address lines, locality, administrative area, postal code, and country.

Configuration #

The package reads the latest MD_suiteSetting__c record named webServiceOptions.

Use this record to supply the Melissa customer ID and the Global Address options described in the Global Address Object Reference Guide.

Apex Use #

String outcome = MDPERSONATOR.MD_GlobalAddressWSExt.doGlobalAddress(recordId);

Treat outcome as package completion status. Do not treat it as a Melissa result code.

Official Service Reference #

See Melissa Global Address Verification documentation for service fields and result codes.

API Reference Guide #

This guide describes the request and response that MD_GlobalAddressWSExt uses. It does not describe a generic Melissa Cloud API request.

Package Endpoint #

The package sends a JSON POST request to this named credential path:

callout:<namespace>MelissaData_GlobalAddress_API/v3/WEB/GlobalAddress/doGlobalAddress

The package sets Accept and Content-Type to application/json.

Package Request Envelope #

MD_GlobalAddressWSExt builds one JSON object for each callout. Do not send the generic query parameters id, opt, a1, loc, or ctry when you use this package method.

{
    "TransmissionReference": "package-generated reference",
    "CustomerID": "URL-encoded customer ID",
    "Options": "package-generated options",
    "Records": [
        {
        "RecordID": "Salesforce record ID",
        "Organization": "mapped value",
        "AddressLine1": "mapped value",
        "AddressLine2": "mapped value",
        "AddressLine3": "mapped value",
        "AddressLine4": "mapped value",
        "AddressLine5": "mapped value",
        "AddressLine6": "mapped value",
        "AddressLine7": "mapped value",
        "AddressLine8": "mapped value",
        "Locality": "mapped value",
        "AdministrativeArea": "mapped value",
        "PostalCode": "mapped value",
        "Country": "mapped value"
        }
    ]
}

The package gets CustomerID from the latest MD_suiteSetting__c record named webServiceOptions.

The package builds Options from these fields on that settings record:

Setting Field	Package Option
`geocode__c`	`OutputGeo`
`countryOfOrigin__c`	`CountryOfOrigin`
`outputScript__c`	`OutputScript`
`gavDeliveryLines__c`	`DeliveryLines`
`gavDetailedResults__c`	`DetailedResults`
`gavAreaDetails__c`	`AreaDetails`
`gavIncludeRemnant__c`	`IncludeRemnant`
`gavUSExtras__c`	`USExtras`
`gavUSPreferredCityNames__c`	`USPreferredCityNames`
`gavGBExtras__c`	`GBExtras`
`gavMelissaCityKeys__c`	`MelissaCityKeys`
`gavExtendedDateTime__c`	`ExtendedDateTime`
`gavUSStandardizationType__c`	`USStandardizationType`
`gavLineSeparator__c`	`LineSeparator`

Package Response and Output #

The package reads response records from the service JSON. It assigns the active mapping name to each response record.

The package saves each matched response to MD_globalAddressResult__c. It updates a Salesforce record only for output entries configured in a Custom Mapping.

The package can map these response values when the corresponding output entry exists:

Custom Mapping Output Key	Response Field	Description
`globalAddressResult`	`MD_globalAddressResult__c.Id`	Lookup to the MD_globalAddressResult__c record created for this verification.
`resultCodes`	`Results__c`	Comma-delimited result codes returned by the service.
`addressLine1` through `addressLine8`	Matching `AddressLine1__c` through `AddressLine8__c`	The standardized or corrected contents of the input address line.
`postalCode`	`PostalCode__c`	ZIP code. The standardized contents of the postal code element.
`locality`	`Locality__c`	City. The standardized contents of the locality element.
`administrativeArea`	`AdministrativeArea__c`	State or province. The standardized contents of the administrative area element.
`country`	`CountryName__c`	The standardized contents of the country name element.
`country2`	`CountryISO3166_1_Alpha2__c`	The two-letter ISO 3166-1 country code.
`country3`	`CountryISO3166_1_Alpha3__c`	The three-letter ISO 3166-1 country code.
`geolocation`	`Latitude__c and Longitude__c`	The latitude and longitude coordinates of the delivery point.
`organization`	`Organization__c`	The organization name associated with the address.
`FormattedAddress`	`FormattedAddress__c`	The address formatted for mailing according to the destination country format.
`AddressKey`	`AddressKey__c`	The address key assigned by the postal authority for the country.
`MelissaAddressKey`	`MelissaAddressKey__c`	The globally unique Melissa address key that persistently identifies the address.

The package also supports configured outputs for returned address components, postal data, delivery data, and geocoding data. Review the Custom Mapping before you depend on an output field.

The method return value is not the service response. Read the mapped result-code field or the Results__c field on MD_globalAddressResult__c.

Official Service Reference #

For the Melissa Cloud API field definitions and result-code meanings, see Melissa Global Address Verification documentation.

Global Email #

Single Record Processing #

Global Email processes one Salesforce record through MD_GlobalEmailWSExt.

Introduction #

The package gets the input email from a globalEmail Custom Mapping. It sends the package JSON envelope to Melissa. It saves the response in MD_globalEmailResult__c and applies configured output mappings.

See Package Request Envelope for the actual request format.

How to use Lightning Quick Action #

Before you use the action, add the package action to the active record page layout.

Open a record that has a Global Email Custom Mapping.
Start the configured Global Email quick action.
Wait for the package to process the record.
Review the configured output fields or MD_globalEmailResult__c.

Apex Use #

Use the synchronous method for one record.

String outcome = MDPERSONATOR.MD_GlobalEmailWSExt.doGlobalEmail(recordId);

After processing, the method returns the literal Success. It does not return a Melissa result code.

Read the configured resultCodes output field or MD_globalEmailResult__c.Results__c for the service result codes.

Trigger Use #

Call doOneGlobalEmail(recordId) from trigger logic when the callout must run asynchronously. The method has @Future(callout=true) and returns no value.

Official Service Reference #

See Melissa Global Email documentation for service behavior and result codes.

Batch Processing #

Global Email Batch Processing validates email deliverability across large record datasets asynchronously.

Introduction #

Batch processing uses MD_GlobalEmailBatch to process thousands of email records. The batch framework selects records that match SOQL criteria and groups requests into batches of 100. It calls Melissa Global Email services and stores verification outputs and result codes on Salesforce objects.

Batch Job Flow #

This flow shows how the batch job processes email records.

Diagram flow

SOQL query → Matching Salesforce records
Matching Salesforce records → Batches of 100 records
Batches of 100 records → MD_GlobalEmailBatch
MD_GlobalEmailBatch → Melissa Global Email service
Melissa Global Email service → Verification outputs and result codes
Verification outputs and result codes → Salesforce objects

How to use the Clean Suite Batch interface #

Follow these steps to launch an email batch verification job:

Open the Clean Suite app from the App Launcher.
Click the Clean Suite Batch tab.
Select Global Email from the Engine menu.
Select the target Salesforce Object (for example Contact or Lead).
Select a configured Field Mapping.
(Optional) Provide a custom SOQL WHERE clause (for example Email != NULL AND Clean_Suite_Global_Email_Result__c = NULL).
Click Run Batch.
Check job completion in Setup → Async Apex Jobs.

Advanced Batch Processing #

Exposed Methods #

Launch email batch processing programmatically with MD_CleanSuiteBatchController:

public static Id executeBatchJob(
  String Engine,              // 'MD_GlobalEmailBatch'
  String BatchObject,         // Object API name (for example 'Contact')
  String Query,               // SOQL query string
  String Mapping,             // Custom Mapping record Name
  Boolean RecordUpdate,       // Set true to update source records
  Boolean ProcessAll,         // Set true to re-process verified records
  Boolean CustomQuery,        // Set true when passing custom SOQL
  String SmartMoverListName,  // Pass empty string
  String SmartMoverJobId      // Pass empty string
)

Sample Code #

Use this Apex snippet to execute a Global Email batch job programmatically:

// Configure parameters for Global Email batch job
String engine = 'MD_GlobalEmailBatch';
String objectName = 'Lead';
String query = 'SELECT Id FROM Lead WHERE Email != NULL AND Clean_Suite_Global_Email_Result__c = NULL';
String mappingName = 'Lead Email Mapping';
Boolean updateTarget = true;
Boolean processAllRecords = false;
Boolean customQueryFlag = true;

// Run batch job
Id jobId = MDPERSONATOR.MD_CleanSuiteBatchController.executeBatchJob(
  engine,
  objectName,
  query,
  mappingName,
  updateTarget,
  processAllRecords,
  customQueryFlag,
  '',
  ''
);

Best Practices #

Filter Out Blank Emails: Exclude null or empty email fields in your SOQL WHERE clause to avoid wasted callout requests.
Handle Catch-All Domains: Use Admin Panel settings to enable catch-all detection. This setting flags catch-all domain servers without marking email addresses as invalid.
Monitor Governor Limits: Set batch chunk size to 100 records to prevent callout timeout exceptions during peak network latency.

Service Tiers #

Global Email validates a mailbox in one of two modes. The mode comes from the VerifyMailBox option.

EXPRESS #

Express checks a submitted email against a cached database of known good and known bad addresses. Melissa caches each submitted email for a 90-day lookup cycle. Use Express when speed and throughput matter most.

Express does not perform a real-time mailbox check.

PREMIUM #

Premium performs a real-time mailbox check. It uses domain-specific logic, SMTP commands, and other proprietary Melissa mechanisms to validate a mailbox. Use Premium when you need the highest level of mailbox verification.

Most mailbox checks take milliseconds. Some take up to the TimeToWait value, which defaults to 25 seconds. Choose Express for a time-sensitive process.

Mode the package sends #

The Melissa service defaults to Premium. The Clean Suite admin setting geVerifyMode__c defaults to EXPRESS. The package sends the mode that this setting holds.

Result Codes #

Global Email returns result codes that indicate the validation outcome. The codes fall into two categories: record-level codes and service-level codes.

Record-level codes apply to individual email records. Service-level codes apply to the request as a whole.

For detailed guidance on interpreting and using result codes, see Result Codes.

Engineering Reference #

Exposed Methods #

MD_GlobalEmailWSExt.doGlobalEmail(Id recordId)

Item	Value
Scope	`global static String`
Processing	Synchronous
Input	Salesforce record ID
Success return	Literal `Success`
Empty return	`''` when the initial object or result-object field-access check fails, or when no Custom Mapping exists for the record object

The package method does not return a Melissa result code. After processing, it returns the literal Success.

Read the configured resultCodes output field or MD_globalEmailResult__c.Results__c for the service result codes.

MD_GlobalEmailWSExt.doOneGlobalEmail(Id recordId)

Item	Value
Scope	`global static void`
Processing	`@Future(callout=true)`
Input	Salesforce record ID
Return	No value

doOneGlobalEmail calls doGlobalEmail in an asynchronous transaction.

Synchronous Workflow #

Call doGlobalEmail with one Salesforce record ID.
The package checks object and result-object field access.
The package reads Custom Mappings for the record object.
The package gets the mapped email input value.
The package sends the package JSON envelope to Global Email.
The package saves the response in MD_globalEmailResult__c.
The package applies configured output mappings to the source record.
The package returns Success.

The package ignores mappings whose service value is not globalEmail.

Configuration #

The package reads customerId__c and geVerifyMode__c from an MD_suiteSetting__c record named webServiceOptions.

See Package Request Envelope for the exact request fields.

Apex Use

String outcome = MDPERSONATOR.MD_GlobalEmailWSExt.doGlobalEmail(recordId);

Use outcome only to check package completion. Do not use it as a Melissa result code.

Official Service Reference #

See Melissa Global Email documentation for service fields and result codes.

API Reference Guide #

This guide describes the request and response that MD_GlobalEmailWSExt uses. It does not describe a generic Melissa Cloud API request.

Package Endpoint #

The package sends a JSON POST request to this named credential path:

callout:<namespace>MelissaData_GlobalEmail_API/v4/WEB/GlobalEmail/doGlobalEmail

The package sets Accept and Content-Type to application/json.

Package Request Envelope #

MD_GlobalEmailWSExt builds one JSON object for each callout. Do not send generic GET parameters or request XML when you use this package method.

{
  "TransmissionReference": "package-generated reference",
  "CustomerID": "URL-encoded customer ID",
  "Options": "VerifyMailBox:<configured mode>",
  "Records": [
    {
      "RecordID": "Salesforce record ID",
      "Email": "mapped value"
    }
  ]
}

The package gets CustomerID and geVerifyMode__c from an MD_suiteSetting__c record named webServiceOptions.

The package adds VerifyMailBox:<geVerifyMode__c> only when geVerifyMode__c contains a value. The package sends an empty Options string when the setting has no value.

The package gets Email from a Custom Mapping input entry named email.

Package Response and Mapped Outputs #

The package reads response records from the service JSON. It saves each matched response to MD_globalEmailResult__c.

The package updates the source Salesforce record only for output entries configured in a Custom Mapping.

Custom Mapping Output Key	Response Field	Description
`globalEmailResult`	`MD_globalEmailResult__c`	Lookup to the `MD_globalEmailResult__c` record created for this verification.
`resultCodes`	`Results__c`	Comma-delimited result codes returned by the service.
`email`	`EmailAddress__c`	The email address to be verified.
`DeliverabilityConfidenceScore`	`DeliverabilityConfidenceScore__c`	The probability, as a percentage from 0 to 100, that an email sent to this mailbox will be delivered successfully.
`MailboxName`	`MailboxName__c`	The mailbox or user name portion of the email address. This is the text before the `@` character.
`DomainName`	`DomainName__c`	The domain name portion of the email address. This is the text between the `@` and the `.` characters.
`DomainAuthenticationStatus`	`DomainAuthenticationStatus__c`	The security protocols used on the receiving mail server.
`TopLevelDomain`	`TopLevelDomain__c`	The description for the top-level domain of the email address. For example, `com` is Commercial.
`TopLevelDomainName`	`TopLevelDomainName__c`	The top-level domain name of the email address. This is the text after the `.`, for example `com`.
`DateChecked`	`DateChecked__c`	The date the email was validated. The value is UTC Unix time (epoch time) in the `MM/DD/YYYY H:MM:SS` format.
`EmailAgeEstimated`	`EmailAgeEstimated__c`	The estimated minimum age of the email in days, based on historical data. The value is zero when no historical data exists for the email.
`DomainAgeEstimated`	`DomainAgeEstimated__c`	The estimated age of the domain in days.
`DomainExpirationDate`	`DomainExpirationDate__c`	The date the domain expires, in the `YYYY-MM-DDTHH:MM:SS` format. This is when the domain will be renewed or becomes available to buy.
`DomainCreatedDate`	`DomainCreatedDate__c`	The date the domain was created in the `YYYY-MM-DDTHH:MM:SS` format.
`DomainUpdatedDate`	`DomainUpdatedDate__c`	The date the domain was last updated in the `YYYY-MM-DDTHH:MM:SS` format.
`DomainEmail`	`DomainEmail__c`	The email associated with the domain owner.
`DomainOrganization`	`DomainOrganization__c`	The company associated with the domain owner.
`DomainAddress1`	`DomainAddress1__c`	The address of the DomainOrganization.
`DomainLocality`	`DomainLocality__c`	The city of the DomainOrganization.
`DomainAdministrativeArea`	`DomainAdministrativeArea__c`	The state of the DomainOrganization.
`DomainPostalCode`	`DomainPostalCode__c`	The postal code of the DomainOrganization.
`DomainCountry`	`DomainCountry__c`	The country of the DomainOrganization.
`DomainCountryCode`	`DomainCountryCode__c`	The country code of the DomainCountry.
`DomainAvailability`	`DomainAvailability__c`	Shows whether the domain is available for purchase.
`DomainPrivateProxy`	`DomainPrivateProxy__c`	Shows whether the domain is behind a private proxy.
`PrivacyFlag`	`PrivacyFlag__c`	Shows whether the email is subject to additional privacy regulations, such as GDPR. Returns `Y` for yes and `N` for no.
`MXServer`	`MXServer__c`	Available with a premium subscription only. The mail exchange (MX) server used to validate the email.
`DomainTypeIndicator`	`DomainTypeIndicator__c`	Predicts whether the email belongs to a person or an organization, based on the domain.
`BreachCount`	`BreachCount__c`	The number of known data breaches that involve this email account.

Synchronous Method Return Value #

doGlobalEmail(Id recordId) does not return a Melissa result code. After processing, the method returns the literal string Success.

The method returns an empty string when its initial object or result-object field-access check fails. It also returns an empty string when no Custom Mapping exists for the record object.

Read the configured resultCodes output field or MD_globalEmailResult__c.Results__c for service result codes.

Clean Suite for CRM: Salesforce Reference Guide

Contents

Clean Suite for CRM: Salesforce Reference Guide#