Add DFP Email Risk endpoint (#279)

Co-authored-by: Stytch Codegen Bot <support@stytch.com>

Author: ci-stytch

stytch/config/version.go

@@ -1,3 +1,3 @@
 package config
 
-const APIVersion = "17.0.0"
+const APIVersion = "17.1.0"

stytch/consumer/fraud.go

@@ -15,6 +15,7 @@ type FraudClient struct {
 	Fingerprint    *FraudFingerprintClient
 	Rules          *FraudRulesClient
 	VerdictReasons *FraudVerdictReasonsClient
+	Email          *FraudEmailClient
 }
 
 func NewFraudClient(c stytch.Client) *FraudClient {
@@ -24,5 +25,6 @@ func NewFraudClient(c stytch.Client) *FraudClient {
 		Fingerprint:    NewFraudFingerprintClient(c),
 		Rules:          NewFraudRulesClient(c),
 		VerdictReasons: NewFraudVerdictReasonsClient(c),
+		Email:          NewFraudEmailClient(c),
 	}
 }

stytch/consumer/fraud/email/types.go

@@ -0,0 +1,51 @@
+package email
+
+// !!!
+// WARNING: This file is autogenerated
+// Only modify code within MANUAL() sections
+// or your changes may be overwritten later!
+// !!!
+
+import (
+	"github.com/stytchauth/stytch-go/v17/stytch/consumer/fraud"
+)
+
+// RiskParams: Request type for `Email.Risk`.
+type RiskParams struct {
+	// EmailAddress: The email address to check.
+	EmailAddress string `json:"email_address,omitempty"`
+}
+
+// RiskResponse: Response type for `Email.Risk`.
+type RiskResponse struct {
+	// RequestID: Globally unique UUID that is returned with every API call. This value is important to log for
+	// debugging purposes; we may ask for this value to help identify a specific API call when helping you
+	// debug an issue.
+	RequestID string `json:"request_id,omitempty"`
+	// AddressInformation: Information about the email address.
+	AddressInformation fraud.AddressInformation `json:"address_information,omitempty"`
+	// DomainInformation: Information about the email domain.
+	DomainInformation fraud.DomainInformation `json:"domain_information,omitempty"`
+	// Action: The suggested action based on the attributes of the email address. The available actions are:
+	//   * `ALLOW` - This email is most likely safe to send to and not fraudulent.
+	//   * `BLOCK` - This email is invalid or exhibits signs of fraud. We recommend blocking the end user.
+	//   * `CHALLENGE` - This email has some potentially fraudulent attributes. We recommend increased friction
+	// such as 2FA or other forms of extended user verification before allowing the privileged action to
+	// proceed.
+	//
+	Action RiskResponseAction `json:"action,omitempty"`
+	// RiskScore: A score from 0 to 100 indicating how risky the email is. 100 is the most risky.
+	RiskScore int32 `json:"risk_score,omitempty"`
+	// StatusCode: The HTTP status code of the response. Stytch follows standard HTTP response status code
+	// patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX
+	// are server errors.
+	StatusCode int32 `json:"status_code,omitempty"`
+}
+
+type RiskResponseAction string
+
+const (
+	RiskResponseActionALLOW     RiskResponseAction = "ALLOW"
+	RiskResponseActionCHALLENGE RiskResponseAction = "CHALLENGE"
+	RiskResponseActionBLOCK     RiskResponseAction = "BLOCK"
+)

stytch/consumer/fraud/types.go

@@ -20,12 +20,37 @@ type ASNProperties struct {
 	Network string `json:"network,omitempty"`
 }
 
+// AddressInformation:
+type AddressInformation struct {
+	// HasKnownBounces: Whether email sent to this address is known to have bounced previously.
+	HasKnownBounces bool `json:"has_known_bounces,omitempty"`
+	// HasValidSyntax: Whether this email address is valid.
+	HasValidSyntax bool `json:"has_valid_syntax,omitempty"`
+	// IsSuspectedRoleAddress: Whether the local part of the email appears to be a role or group, rather than
+	// an individual end user.
+	IsSuspectedRoleAddress bool `json:"is_suspected_role_address,omitempty"`
+	// NormalizedEmail: The normalized email address after removing '.' characters and any characters after a
+	// '+'.
+	NormalizedEmail string `json:"normalized_email,omitempty"`
+	// TumblingCharacterCount: The number of '.' and '+' characters in the email address. A higher tumbling
+	// count indicates a higher potential for fraud.
+	TumblingCharacterCount int32 `json:"tumbling_character_count,omitempty"`
+}
+
 // BrowserProperties:
 type BrowserProperties struct {
 	// UserAgent: The user agent of the user's browser.
 	UserAgent string `json:"user_agent,omitempty"`
 }
 
+// DomainInformation:
+type DomainInformation struct {
+	// HasMXOrARecord: Whether the email has appropriate DNS records to deliver a message.
+	HasMXOrARecord bool `json:"has_mx_or_a_record,omitempty"`
+	// IsDisposableDomain: Whether the email domain is known to be disposable.
+	IsDisposableDomain bool `json:"is_disposable_domain,omitempty"`
+}
+
 // Fingerprints:
 type Fingerprints struct {
 	// NetworkFingerprint: Combination of signals associated with a specific network commonly known as TLS

stytch/consumer/fraud_email.go

@@ -0,0 +1,66 @@
+package consumer
+
+// !!!
+// WARNING: This file is autogenerated
+// Only modify code within MANUAL() sections
+// or your changes may be overwritten later!
+// !!!
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/stytchauth/stytch-go/v17/stytch"
+	"github.com/stytchauth/stytch-go/v17/stytch/consumer/fraud/email"
+	"github.com/stytchauth/stytch-go/v17/stytch/stytcherror"
+)
+
+type FraudEmailClient struct {
+	C stytch.Client
+}
+
+func NewFraudEmailClient(c stytch.Client) *FraudEmailClient {
+	return &FraudEmailClient{
+		C: c,
+	}
+}
+
+// Risk: Get risk information for a specific email address.
+// The response will contain a recommended action (`ALLOW`, `BLOCK`, or `CHALLENGE`) and a more granular
+// `risk_score`.
+// You can also check the `address_information` and `domain_information` fields for more information about
+// the email address and email domain.
+//
+// This feature is in beta. Reach out to us
+// [here](mailto:fraud-team@stytch.com?subject=Email_Intelligence_Early_Access) if you'd like to request
+// early access.
+func (c *FraudEmailClient) Risk(
+	ctx context.Context,
+	body *email.RiskParams,
+) (*email.RiskResponse, error) {
+	var jsonBody []byte
+	var err error
+	if body != nil {
+		jsonBody, err = json.Marshal(body)
+		if err != nil {
+			return nil, stytcherror.NewClientLibraryError("error marshaling request body")
+		}
+	}
+
+	headers := make(map[string][]string)
+
+	var retVal email.RiskResponse
+	err = c.C.NewRequest(
+		ctx,
+		stytch.RequestParams{
+			Method:      "POST",
+			Path:        "/v1/email/risk",
+			QueryParams: nil,
+			Body:        jsonBody,
+			V:           &retVal,
+			Headers:     headers,
+			BaseURLType: "FRAUD",
+		},
+	)
+	return &retVal, err
+}