Add DFP Email Risk endpoint (#306)

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

Author: ci-stytch

stytch/consumer/api/fraud.py

@@ -6,6 +6,7 @@
 
 from __future__ import annotations
 
+from stytch.consumer.api.fraud_email import Email
 from stytch.consumer.api.fraud_fingerprint import Fingerprint
 from stytch.consumer.api.fraud_rules import Rules
 from stytch.consumer.api.fraud_verdict_reasons import VerdictReasons
@@ -35,3 +36,8 @@ def __init__(
             sync_client=self.sync_client,
             async_client=self.async_client,
         )
+        self.email = Email(
+            api_base=self.api_base,
+            sync_client=self.sync_client,
+            async_client=self.async_client,
+        )

stytch/consumer/api/fraud_email.py

@@ -0,0 +1,66 @@
+# !!!
+# WARNING: This file is autogenerated
+# Only modify code within MANUAL() sections
+# or your changes may be overwritten later!
+# !!!
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from stytch.consumer.models.fraud_email import RiskResponse
+from stytch.core.api_base import ApiBase
+from stytch.core.http.client import AsyncClient, SyncClient
+
+
+class Email:
+    def __init__(
+        self, api_base: ApiBase, sync_client: SyncClient, async_client: AsyncClient
+    ) -> None:
+        self.api_base = api_base
+        self.sync_client = sync_client
+        self.async_client = async_client
+
+    def risk(
+        self,
+        email_address: str,
+    ) -> RiskResponse:
+        """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.
+
+        Fields:
+          - email_address: The email address to check.
+        """  # noqa
+        headers: Dict[str, str] = {}
+        data: Dict[str, Any] = {
+            "email_address": email_address,
+        }
+
+        url = self.api_base.url_for("/v1/email/risk", data)
+        res = self.sync_client.post(url, data, headers)
+        return RiskResponse.from_json(res.response.status_code, res.json)
+
+    async def risk_async(
+        self,
+        email_address: str,
+    ) -> RiskResponse:
+        """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.
+
+        Fields:
+          - email_address: The email address to check.
+        """  # noqa
+        headers: Dict[str, str] = {}
+        data: Dict[str, Any] = {
+            "email_address": email_address,
+        }
+
+        url = self.api_base.url_for("/v1/email/risk", data)
+        res = await self.async_client.post(url, data, headers)
+        return RiskResponse.from_json(res.response.status, res.json)

stytch/consumer/models/fraud.py

@@ -63,6 +63,23 @@ class ASNProperties(pydantic.BaseModel):
     network: str
 
 
+class AddressInformation(pydantic.BaseModel):
+    """
+    Fields:
+      - has_known_bounces: Whether email sent to this address is known to have bounced previously.
+      - has_valid_syntax: Whether this email address is valid.
+      - is_suspected_role_address: Whether the local part of the email appears to be a role or group, rather than an individual end user.
+      - normalized_email: The normalized email address after removing '.' characters and any characters after a '+'.
+      - tumbling_character_count: The number of '.' and '+' characters in the email address. A higher tumbling count indicates a higher potential for fraud.
+    """  # noqa
+
+    has_known_bounces: bool
+    has_valid_syntax: bool
+    is_suspected_role_address: bool
+    normalized_email: str
+    tumbling_character_count: int
+
+
 class BrowserProperties(pydantic.BaseModel):
     """
     Fields:
@@ -72,6 +89,17 @@ class BrowserProperties(pydantic.BaseModel):
     user_agent: str
 
 
+class DomainInformation(pydantic.BaseModel):
+    """
+    Fields:
+      - has_mx_or_a_record: Whether the email has appropriate DNS records to deliver a message.
+      - is_disposable_domain: Whether the email domain is known to be disposable.
+    """  # noqa
+
+    has_mx_or_a_record: bool
+    is_disposable_domain: bool
+
+
 class Fingerprints(pydantic.BaseModel):
     """
     Fields:

stytch/consumer/models/fraud_email.py

@@ -0,0 +1,37 @@
+# !!!
+# WARNING: This file is autogenerated
+# Only modify code within MANUAL() sections
+# or your changes may be overwritten later!
+# !!!
+
+from __future__ import annotations
+
+import enum
+
+from stytch.consumer.models.fraud import AddressInformation, DomainInformation
+from stytch.core.response_base import ResponseBase
+
+
+class RiskResponseAction(str, enum.Enum):
+    ALLOW = "ALLOW"
+    CHALLENGE = "CHALLENGE"
+    BLOCK = "BLOCK"
+
+
+class RiskResponse(ResponseBase):
+    """Response type for `Email.risk`.
+    Fields:
+      - address_information: Information about the email address.
+      - domain_information: Information about the email domain.
+      - 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.
+
+      - risk_score: A score from 0 to 100 indicating how risky the email is. 100 is the most risky.
+    """  # noqa
+
+    address_information: AddressInformation
+    domain_information: DomainInformation
+    action: RiskResponseAction
+    risk_score: int

stytch/version.py

@@ -1 +1 @@
-__version__ = "14.1.0"
+__version__ = "14.2.0"