Email masking policy (standard)

Edit online

The Email category provides standard masking policy formats for email domain suffixes (TLDs), full email addresses, and name-based email addresses. Use these formats to mask email data while preserving structural validity.

Parameters

The Email masking policy accepts the following parameters.

Table 1. Email masking policy parameters
Parameter	Required	Type	Description
`name`	Yes	String	The format name. Must be one of: `EmailDomainSuffix_CaseSensitive`, `EnglishEmailCaseSensitive`, `NameBasedEmail`.
`type`	Yes	String	The processor type. Accepted values depend on the format. See each format section for supported processors.
`config`	No	Object	Pass `{}` or omit entirely. No additional configuration keys are supported for any address format.

EmailDomainSuffix_CaseSensitive format

Masks an email top-level domain (TLD) suffix by replacing it with a different value drawn from a dictionary of 263 real TLD entries. The format is case-sensitive - all dictionary entries are stored in lowercase, so COM and Org are treated as non-dictionary inputs. All outputs are returned in lowercase. Supports RandomFormatFabricationProcessor and RepeatableFormatFabricationProcessor only.

The 263-entry dictionary includes generic TLDs (com, org, net), ISO 3166-1 country codes, and regional codes (eu, uk, su, tp). Maximum output length is 4 characters (arpa).

Dictionary inputs (lowercase only)

Example input	Note
`com`	Generic TLD - rank 0
`org`	Generic TLD
`uk`	Regional code
`arpa`	The only 4-letter entry in the dictionary

Non-dictionary inputs

Example input	Reason
`COM`	Uppercase - dictionary contains only lowercase entries
`Org`	Mixed case - dictionary contains only lowercase entries
`google`	6 letters - no entry of this value or length exists
`co.uk`	Contains a dot - no multi-label entries

Processors

RandomFormatFabricationProcessor

Generates a new fabricated lowercase TLD on every invocation. Non-deterministic.

Use when: Masking a TLD column where referential consistency is not required.

Input	Output (run 1)	Output (run 2)
`com`	`de`	`jp`
`org`	`uk`	`au`

RepeatableFormatFabricationProcessor

Produces a deterministic fabricated TLD. The same input produces the same output for the same IV. Note that COM and com take different paths and produce different outputs even for the same IV.

Use when: Masking a TLD column that is part of a key or join where the same source value must consistently map to the same masked value.

Configuration examples

RandomFormatFabricationProcessor

{
  "column_name_source": "email_tld",
  "column_name_target": "email_tld_masked",
  "masking_properties": {
    "magen_function": {
      "name": "EmailDomainSuffix_CaseSensitive",
      "type": "RandomFormatFabricationProcessor",
      "config": {}
    }
  }
}

RepeatableFormatFabricationProcessor

{
  "column_name_source": "email_tld",
  "column_name_target": "email_tld_masked",
  "masking_properties": {
    "magen_function": {
      "name": "EmailDomainSuffix_CaseSensitive",
      "type": "RepeatableFormatFabricationProcessor",
      "config": {}
    }
  }
}

Known limitations

This format masks TLD only - not full email addresses: EmailDomainSuffix_CaseSensitive operates on isolated TLD tokens (com, uk), not on full email addresses. Applying it to a full email address column will treat the entire email string as a non-dictionary input and return a TLD token - not a masked email.
Case sensitivity affects the masking path: com, COM, and Com are three distinct inputs. Only com is in the dictionary. Normalize to lowercase before masking.
No redaction or tokenization support: FormatPreservingRedactionProcessor and FormatPreservingTokenizationProcessor are not supported.
NULL handling: NULL values are passed through unchanged.

EnglishEmailCaseSensitive format

Masks a full email address by replacing it with a structurally valid fabricated or tokenized email whose local-part and host-part length profile matches the input. The format partitions the email address space into 56 non-overlapping length buckets based on local-part and host-part character counts. All processors operate within the bucket matched by the input - the output always falls in the same bucket. The maximum output length is 222 characters. All four processors are supported.

The TLD must always be lowercase - emails with uppercase TLDs such as user@example.COM are out-of-domain.

Valid input values

Input	Notes
`very.common@example.com`	All-lowercase local and host
`Nyju.Shanmukhan@hdfcsec.com`	Mixed-case local - accepted; TLD `com` lowercase
`prettyandsimple@example.co.uk`	Multi-label host; `uk` in TLD dictionary
`soos@43.243.423.432`	IP-address host - accepted
`user@ab.co`	Minimum valid form - host `ab` is 2 characters

Invalid input values

Value	Reason	`FormatPreservingRedactionProcessor`	`FormatPreservingTokenizationProcessor`	`RandomFormatFabricationProcessor` / `RepeatableFormatFabricationProcessor`
`john@example.COM`	Uppercase TLD	`IllegalArgumentException`	`MagenPayloadException`	Returns random valid email (largest bucket)
`user+tag@example.com`	`+` not in character set	`IllegalArgumentException`	`MagenPayloadException`	Returns random valid email (largest bucket)
`@example.com`	Empty local part	`IllegalArgumentException`	`MagenPayloadException`	Returns random valid email (largest bucket)
`a@b.com`	Host part 1 character - below 2-character minimum	`IllegalArgumentException`	`MagenPayloadException`	Returns random valid email (largest bucket)

Processors

FormatPreservingRedactionProcessor

Replaces every valid input with the rank-0 element of its matched bucket. All emails that fall in the same bucket produce the same canonical output.

Use when: Deterministic suppression where a uniform per-bucket placeholder is sufficient.

Input	Bucket	Output
`user@example.com`	(10, 10)	`0..........@------------.com`
`Nyju.Shanmukhan@hdfcsec.com`	(15, 10)	`0...............@------------.com`

FormatPreservingTokenizationProcessor

Produces a deterministic token within the matched bucket. The same input always produces the same output for the same IV.

Use when: Masking an email column used in a join or group-by where the same source email must consistently map to the same masked value.

Input	Bucket	Output
`user@example.com`	(10, 10)	`3drWTQyfLwC@chMVc-sAE4pI.gb`

RandomFormatFabricationProcessor

Generates a new fabricated email on every invocation in the same bucket as the input. Non-deterministic.

Use when: Masking a non-key email column where run-to-run consistency is not required.

RepeatableFormatFabricationProcessor

Produces a deterministic fabricated email in the same bucket as the input. The same input and IV always produce the same output.

Use when: Masking a primary-key or foreign-key email column where referential integrity must be maintained across tables and job runs.

Configuration examples

FormatPreservingTokenizationProcessor

{
  "column_name_source": "work_email",
  "column_name_target": "work_email_masked",
  "masking_properties": {
    "magen_function": {
      "name": "EnglishEmailCaseSensitive",
      "type": "FormatPreservingTokenizationProcessor",
      "config": { "mode": "tokenize" }
    }
  }
}

RepeatableFormatFabricationProcessor

{
  "column_name_source": "contact_email",
  "column_name_target": "contact_email_masked",
  "masking_properties": {
    "magen_function": {
      "name": "EnglishEmailCaseSensitive",
      "type": "RepeatableFormatFabricationProcessor",
      "config": {}
    }
  }
}

Known limitations

TLD must be lowercase: The TLD must be lowercase. Emails ending in uppercase or mixed-case TLDs are out-of-domain for the redaction and tokenization processors, which raise IllegalArgumentException. Fabrication processors apply the hash path and return a valid email in the largest bucket.
FormatPreservingRedactionProcessor produces the same output for all emails in the same bucket: Use FormatPreservingTokenizationProcessor when individual per-address differentiation is required.
+ addressing is not supported: Subaddressing (for example, user+tag@example.com) is out-of-domain. Fabrication processors apply the hash path; redaction and tokenization processors raise an error.
Out-of-domain inputs produce outputs in the largest bucket: When fabrication processors handle an out-of-domain input via the hash path, the output typically lands in the largest length bucket (63-character local part, up to 150-character host part). The output email is structurally much longer than the input.
Host part must be at least 2 characters: An address such as a@b.com - where the host is the single character b - is out-of-domain for all processors.
NULL handling: NULL values are passed through unchanged.

NameBasedEmail format

Masks a name-based email address by replacing each component - first name, last name, domain label, TLD, and optional subdomain - with a fabricated equivalent. The output always conforms to the pattern {FirstName}.{LastName}@{domain-label}.{subdomain}.{tld} (where subdomain is optional). The maximum output length is 45 characters. Supports RandomFormatFabricationProcessor and RepeatableFormatFabricationProcessor only.

Important: NameBasedEmail only matches emails where the local part is exactly one US first name, a dot, and one US last name, in that order. The first name is matched case-insensitively against a 5,163-entry dictionary. The last name is matched case-insensitively against an 88,799-entry dictionary. Generic local parts such as info, admin, or john.doe.jr are out-of-domain.

Dictionary inputs

Input	Notes
`adelia.estrado@aaaa.com`	`Adelia` in first-name dictionary, `Estrado` in last-name dictionary, `com` in TLD dictionary
`roland.margis@abcde.co.il`	Two-level domain: label `abcde`, subdomain `co`, TLD `il`
`Aaron.Smith@example.org`	Mixed-case first/last name - case-insensitive match

Non-dictionary inputs

Value	Reason	Engine behavior
`fake.name@google.com`	`Fake` and `Name` not in first/last name dictionaries	Returns random or deterministic valid name-based email
`john.doe.smith@example.com`	Three name parts - pattern requires exactly `FirstName.LastName`	Returns random or deterministic valid name-based email
`adelia.estrado@EXAMPLE.com`	Uppercase in domain label - domain label must be lowercase	Returns random or deterministic valid name-based email

Processors

RandomFormatFabricationProcessor

Generates a new fabricated name-based email on every invocation. Each sub-part (first name, last name, domain label, TLD) is fabricated independently. Non-deterministic.

Use when: Masking a non-key name-based email column where run-to-run consistency is not required.

RepeatableFormatFabricationProcessor

Produces a deterministic fabricated name-based email. The same input and IV always produce the same output.

Use when: Masking a primary-key or foreign-key name-based email column where consistent output is required across tables and job runs.

Configuration examples

RandomFormatFabricationProcessor

{
  "column_name_source": "employee_email",
  "column_name_target": "employee_email",
  "masking_properties": {
    "magen_function": {
      "name": "NameBasedEmail",
      "type": "RandomFormatFabricationProcessor",
      "config": {}
    }
  }
}

RepeatableFormatFabricationProcessor

{
  "column_name_source": "employee_email",
  "column_name_target": "employee_email",
  "masking_properties": {
    "magen_function": {
      "name": "NameBasedEmail",
      "type": "RepeatableFormatFabricationProcessor",
      "config": {}
    }
  }
}

Known limitations

Requires exact FirstName.LastName local-part pattern: The local part must be exactly one US first name, a dot, and one US last name. Generic, multi-part, or underscore-separated local parts are out-of-domain and are handled via the fabrication hash path.
TLD must be lowercase: The TLD must be lowercase. Emails ending in uppercase or mixed-case TLDs (for example, user@example.COM) are out-of-domain for all processors.
Domain label must be lowercase: The domain label must consist of only lowercase letters. Uppercase letters, digits, and hyphens in the domain label are not accepted.
No redaction or tokenization support: FormatPreservingRedactionProcessor and FormatPreservingTokenizationProcessor are not supported.
Applying to non-string columns does not raise an error: Applying this policy to a non-string column results in a silent type-specific fallback value written to the target column. Only VARCHAR, TEXT, and CHAR columns produce meaningful output.
NULL handling: NULL values are passed through unchanged.