Creating a New Pattern

Before we dive into using the SDK, it's crucial to understand the concept of "patterns" in the context of ZK Email.

What is a Pattern?

A pattern is a template that defines:

1. What information you want to extract from an email

2. How to locate this information within the email structure

3. Which parts of this information should be made public and which should remain private

Think of a pattern as a set of instructions for the ZK Email system to follow when processing an email. It tells the system:

• Where to look in the email (header, body, etc.)

• What to look for (sender email, subject line, specific content, etc.)

• What to reveal and what to keep hidden

Why Create a Pattern?

Creating a pattern is essential because:

Customization

It allows you to tailor the email verification process to your specific needs.

Privacy

You can control what information is revealed and what remains private.

Efficiency

By defining exactly what you need, you optimize the proof generation process.

Reusability

Once created, a pattern can be used multiple times across different applications.

Creating a New Pattern

Now that we understand what patterns are and why they're important, let's create one.

1. Visit the ZK Regex Registry: Go to https://sdk.prove.email/

2. Click on "Submit a new pattern" to create a new pattern.

1. Fill in the Pattern Details:

   • Pattern Title: A descriptive name (e.g., "Email Verification")

   • Description: Explain what your pattern verifies (e.g., "Verifies the sender and subject of an email")

   • Slug: A unique identifier in the format (e.g., "your-name/email-verification")

   • Tags: Categories related to the pattern (comma-delimited)

   • Email Query: Define how to find relevant emails (e.g., "from:[email protected]")

   • Circuit Name: Name for the generated circuit (e.g., "EmailVerifier")

   • Skip Body Hash Check: Set to true if the information you want can fully be retrieved from the headers

   • SHA Precompute Selector: A unique string that is before the extracted data in the email body

   • Use new ZK Regex SDK for circuit generation: Set to true to use the new SDK

2. Define Fields to Extract: For each piece of information you want to extract, add a field:

   • Field Name: Name of the data you're extracting (e.g., "SenderEmail", "Subject")

   • Data Location: Choose whether the data is in the email header or body

   • Parts: Define the regex pattern to match the data. For example:

     {
       "parts": [
         {
           "is_public": false,
           "regex_def": "From: "
         },
         {
           "is_public": true,
           "regex_def": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}"
         }
       ]
     }

3. Submit Your Pattern: Click "Submit" to register your pattern.

4. Wait for Processing: The system will process your pattern and generate the necessary circuits. This may take a few minutes.

Once your pattern is registered and processed, you can use it in your application with the ZK Email SDK.

Pattern Parameters

You can define multiple fields to extract different pieces of information from the email. Each field has the following properties:

Field Name

A unique identifier for this field within your pattern. Use CamelCase and make it descriptive of the data it extracts.

Property	Description	Type
field_name	Pattern name	String

Field Name Example

"field_name": "SenderEmail"

Data Location

Specifies where in the email to look for this information:

• "header": For information in the email headers (From, To, Subject, etc.)

• "body": For information in the main content of the email

Parts

An array of objects that define the regex pattern for extracting information. Each part has two properties:

Property	Description	Type
is_public	Indicates if the matched part is public or private	Boolean
regex_def	Regular expression defining what to match	Regular Expression

Parts Array Example

[
  {
    "is_public": true,
    "regex_def": "[a-zA-Z]+"
  },
  {
    "is_public": false,
    "regex_def": "\\d+"
  }
]

Sender Email Field Example

{
  "field_name": "SenderEmail",
  "data_location": "header",
  "parts": [
    {
      "is_public": false,
      "regex_def": "From: "
    },
    {
      "is_public": true,
      "regex_def": "[a-zA-Z]{3}"
    },
    {
      "is_public": false,
      "regex_def": "[a-zA-Z0-9._%+-]+"
    },
    {
      "is_public": true,
      "regex_def": "@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}"
    }
  ]
}

This field:

1. Looks in the header for the "From:" line

2. Reveals the first 3 letters of the email address

3. Keeps the rest of the local part private

4. Reveals the domain (everything after and including the @)

For an email "[email protected]", this would reveal "[email protected]".

Email Content Field Example

{
  "field_name": "EmailContent",
  "data_location": "body",
  "parts": [
    {
      "is_public": false,
      "regex_def": ".*"
    },
    {
      "is_public": true,
      "regex_def": "Verification code: [A-Z0-9]{6}"
    },
    {
      "is_public": false,
      "regex_def": ".*"
    }
  ]
}

This field:

1. Looks in the email body

2. Keeps everything before the verification code private

3. Reveals a 6-character alphanumeric verification code

4. Keeps everything after the verification code private

For an email body "Your verification code: ABC123. Keep this private.", this would reveal only "Verification code: ABC123".

Advanced Regex Tips

• Use .* to match any character (except newline) any number of times

• Use \s* to match any whitespace characters

• Use ? after a character or group to make it optional

• Use parentheses () to create capture groups for more complex matches

• Use \b for word boundaries to ensure you're matching whole words

Advanced Regex Example

{
  "is_public": true,
  "regex_def": "\\bBalance:\\s*\\$[0-9,]+(\\.[0-9]{2})?"
}

This would match and reveal a balance like "Balance: $1,234.56" in an email.

Best Practices

1. Privacy First: Always consider what information needs to be public and what should remain private. Reveal only what's absolutely necessary.

2. Be Specific: The more specific your regex, the more efficient and secure your pattern will be. Avoid overly broad patterns that might accidentally reveal too much.

3. Test Thoroughly: Before submitting, test your regex patterns with sample emails to ensure they work as expected. Use online regex testers for quick iterations.

4. Document Well: Use clear names and descriptions to make your pattern understandable to others (and your future self).

5. Version Control: If you're updating an existing pattern, consider creating a new version rather than modifying the original. This helps maintain backwards compatibility.

Use Cases Examples

Transaction Verification

Extract and verify transaction amounts and recipient addresses from bank notification emails.

Age Verification

Confirm a user's age from a government ID email without revealing their exact birthdate.

Membership Validation

Verify a user's membership status from an organization's email without revealing other personal details.