Skip to content

STF-2006: Document email verification inputs #1776

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
horgh merged 1 commit into from
Oct 27, 2026
Merged

STF-2006: Document email verification inputs #1776

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 18 additions & 2 deletions content/minfraud/api-documentation/requests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,9 @@ size will be rejected.
},
"email": {
"address": "977577b140bfb7c516e4746204fbdb01",
"domain": "maxmind.com"
"domain": "maxmind.com",
"verification_time": "2026-10-01T14:25:00Z",
"was_verification_successful": true
},
"event": {
"party": "customer",
Expand Down Expand Up @@ -353,7 +355,9 @@ the end-user who initiated the event.
```json
{
"address": "977577b140bfb7c516e4746204fbdb01",
"domain": "maxmind.com"
"domain": "maxmind.com",
"verification_time": "2026-10-01T14:25:00Z",
"was_verification_successful": true
}
```

Expand All @@ -371,6 +375,18 @@ the end-user who initiated the event.

You do not need to pass the email domain input unless you are passing the email address as an MD5 hash. [Learn more about hashed email inputs on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/passing-email-inputs-minfraud#email-hashing)
{{</minfraud-schema-row>}}

{{< minfraud-schema-row key="verification_time" type="request" valueType="string" >}}
The most recent date and time a verification of the email address was attempted, if known. The string must be in the [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format. The time must not be before 1970-01-01T00:00:00Z or more than two days in the future. For a time outside this range, MaxMind ignores the input and returns a warning.

@horgh horgh Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor: the row does not say which time to send for a link-based check.

"The most recent date and time a verification of the email address was attempted" can mean the time you sent the link or the time the user clicked it. For email, these two times can be hours or days apart. For a phone code, the gap is usually minutes, so the phone rows have less of this problem.

Example: merchant A sends the time it sent the link. Merchant B sends the time the user clicked the link. The model gets inconsistent values for the same kind of event.

Suggest: state which moment the time refers to, for example "the time the user confirmed the link, or the time you sent it if the user has not confirmed it". Use the definition that the model expects.

馃 Comment by Claude Opus 5.5.

@horgh horgh Oct 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Likewise

@horgh horgh Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: "most recent" does not say relative to what.

You can score a stored transaction later with /event/time, up to one year in the past. The row does not say whether to send the verification state as of that event or as of now.

Example: a merchant scores a 6-month-old transaction and sends the current state of the email address. The verification_time is then after the event. The web service accepts any time up to two days after the current time, so it does not catch this. The model then sees information from after the event.

Suggest: add "as of the time of the event" or similar to both email rows (this line and line 386). The phone verification rows (lines 487, 493, 595, and 601) have the same wording.

馃 Comment by Claude Opus 5.5.

@horgh horgh Oct 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems likely okay as is, but I guess it could go in the above bucket too.

@horgh horgh Oct 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: the row does not say to leave out the time when no verification was attempted.

The was_verification_successful row says "Do not include this field if you have not performed this check." The phone inputs put the same rule on phone_verification_method. The email inputs have no method field, so no email row gives this rule for verification_time.

Failure scenario: an integration that always sends a value sends a placeholder, such as 1970-01-01T00:00:00Z, when there was no verification. The web service accepts it, because the time is not before the epoch. MaxMind then records a verification attempt that did not occur.

Suggested fix: add "Do not include this field if no verification was attempted." The OpenAPI spec (maxmind/openapi#7) and the client docs copy this text, so they can follow this row.

馃 Comment by Claude Opus 5.5.

@horgh horgh Oct 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like it should be obvious to me, but I guess we could say it. Probably in the same position as the above.


[Learn more about the /email/verification\_time input on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/passing-email-inputs-minfraud)
{{</minfraud-schema-row>}}

{{< minfraud-schema-row key="was_verification_successful" type="request" valueType="boolean" >}}
Whether the most recent verification that the end user controls this email address was successful (e.g. by confirming a link sent to the email address). `true` if the email verification was successful, or `false` if the user failed email verification. Do not include this field if you have not performed this check.

@horgh horgh Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: the example clause is attached to "successful" instead of to "verification".

"...controls this email address was successful (e.g. by confirming a link sent to the email address)" reads as if the link confirmation describes the success. The clause gives an example of the verification method. The phone rows put the method next to the verification ("using the method named in phone_verification_method").

Suggest:

Suggested change
Whether the most recent verification that the end user controls this email address was successful (e.g. by confirming a link sent to the email address). `true` if the email verification was successful, or `false` if the user failed email verification. Do not include this field if you have not performed this check.
Whether the most recent verification that the end user controls this email address, for example by confirming a link sent to the email address, was successful. `true` if the email verification was successful, or `false` if the user failed email verification. Do not include this field if you have not performed this check.

The OpenAPI spec (maxmind/openapi#7) copies this sentence, including the "e.g.", so it can take the same change.

馃 Comment by Claude Opus 5.5.

@horgh horgh Oct 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given this text is as provided, we can probably leave it.

@horgh horgh Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor: the row does not say what to send while a verification is pending.

With a link-based check, time passes between the moment you send the link and the moment the user clicks it. The link can also expire without a click. The row says to send false "if the user failed email verification" and to omit the field "if you have not performed this check". It does not say which rule applies to a link that is sent but not yet confirmed.

Example: a merchant sends a confirmation link at signup and scores the account_creation event before the user clicks it. The merchant can read "performed this check" as "sent the link" and send false. minFraud then sees every normal, not-yet-confirmed signup as a failed verification. This can raise risk scores and cause false positives.

Suggest: add a sentence that says what to do while the result is not known, for example "If the user has not yet completed the verification, do not include this field." Use the rule that the model expects. The phone rows have a smaller form of the same gap (a code is sent but not yet entered).

馃 Comment by Claude Opus 5.5.

@horgh horgh Oct 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Likewise, but maybe worth pinging Miguel?


[Learn more about the /email/was\_verification\_successful input on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/passing-email-inputs-minfraud)
{{</minfraud-schema-row>}}
{{</ schema-table >}}

<!-- prettier-ignore-end -->
Expand Down
13 changes: 13 additions & 0 deletions content/minfraud/release-notes/2026-10-26-new-email-verification-inputs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
+++
title = 'New email verification inputs'
date = 2026-10-26T16:00:00Z
draft = false
+++

We have released new inputs for all minFraud web service customers. They
describe the most recent verification of the email address.

| new input | description |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email/verification_time` | The most recent date and time a verification of the email address was attempted, if known. [Learn more on our developer portal.](/minfraud/api-documentation/requests/#schema--request--email__verification_time) |
| `email/was_verification_successful` | Whether the most recent verification that the end user controls this email address was successful. [Learn more on our developer portal.](/minfraud/api-documentation/requests/#schema--request--email__was_verification_successful) |
Loading