Add email verification inputs

CHANGELOG.md

@@ -6,6 +6,9 @@
   `phone_was_verification_successful`, and `phone_verification_time`
   attributes to `Minfraud::Components::Billing`. They describe the most
   recent verification of the billing phone number.
+* Added the `was_verification_successful` and `verification_time`
+  attributes to `Minfraud::Components::Email`. They describe the most
+  recent verification of the email address.
 * Boolean inputs are now always sent as JSON booleans, and `false` values
   are no longer dropped from the request. Previously, `false` was omitted
   for every boolean input. `true` was sent as the string `"true"` for

README.md

@@ -98,8 +98,10 @@ assessment = Minfraud::Assessments.new(
     username_md5: '4f9726678c438914fa04bdb8c1a24088',
   },
   email: {
-    address: 'test@maxmind.com',
-    domain:  'maxmind.com',
+    address:                     'test@maxmind.com',
+    domain:                      'maxmind.com',
+    verification_time:           '2026-10-01T14:30:00Z',
+    was_verification_successful: true,
   },
   billing: {
     first_name:                        'First',

lib/minfraud/components/email.rb

@@ -31,12 +31,29 @@ class Email < Base
       # @return [Boolean, nil]
       attr_accessor :hash_address
 
+      # Whether the most recent verification of the email address succeeded.
+      # Do not include this field if no verification was attempted.
+      #
+      # @return [Boolean, nil]
+      attr_accessor :was_verification_successful
+
+      # The date and time of the most recent verification of the email
+      # address. The string must be in the RFC 3339 date-time format, e.g.,
+      # "2012-04-12T23:20:50.52Z".
+      #
+      # @see https://datatracker.ietf.org/doc/html/rfc3339
+      #
+      # @return [String, nil]
+      attr_accessor :verification_time
+
       # @param params [Hash] Hash of parameters. Each key/value should
       #   correspond to one of the available attributes.
       def initialize(params = {})
-        @address      = params[:address]
-        @domain       = params[:domain]
-        @hash_address = params[:hash_address]
+        @address                     = params[:address]
+        @domain                      = params[:domain]
+        @hash_address                = params[:hash_address]
+        @was_verification_successful = params[:was_verification_successful]
+        @verification_time           = params[:verification_time]
 
         validate
       end
@@ -72,6 +89,8 @@ def validate
 
         validate_email('email', @address)
         validate_string('domain', 255, @domain)
+        validate_boolean('was_verification_successful', @was_verification_successful)
+        validate_rfc3339('verification_time', @verification_time)
       end
 
       def hash_email_address(address)

spec/components/email_spec.rb

@@ -3,6 +3,21 @@
 require 'spec_helper'
 
 describe Minfraud::Components::Email do
+  describe '#to_json' do
+    [true, false].each do |successful|
+      it "sends was_verification_successful #{successful} as a JSON boolean" do
+        email = described_class.new(
+          verification_time:           '2026-10-01T14:30:00Z',
+          was_verification_successful: successful,
+        )
+        expect(email.to_json).to eq(
+          'verification_time'           => '2026-10-01T14:30:00Z',
+          'was_verification_successful' => successful,
+        )
+      end
+    end
+  end
+
   describe 'validation' do
     before do
       Minfraud.configure { |c| c.enable_validation = 1 }
@@ -16,9 +31,27 @@
       end.to raise_exception(Minfraud::InvalidInputError)
     end
 
+    it 'raises an exception for an invalid was_verification_successful' do
+      expect do
+        described_class.new(
+          was_verification_successful: 'true',
+        )
+      end.to raise_exception(Minfraud::InvalidInputError)
+    end
+
+    it 'raises an exception for an invalid verification_time' do
+      expect do
+        described_class.new(
+          verification_time: '2026-10-01 14:30:00',
+        )
+      end.to raise_exception(Minfraud::InvalidInputError)
+    end
+
     it 'does not raise an exception for valid values' do
       described_class.new(
-        address: 'wstorey@maxmind.com',
+        address:                     'wstorey@maxmind.com',
+        verification_time:           '2026-10-01T14:30:00Z',
+        was_verification_successful: false,
       )
     end