diff --git a/stytch/consumer/api/fraud.py b/stytch/consumer/api/fraud.py index 97cb66e..d5c3b7f 100644 --- a/stytch/consumer/api/fraud.py +++ b/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, + ) diff --git a/stytch/consumer/api/fraud_email.py b/stytch/consumer/api/fraud_email.py new file mode 100644 index 0000000..e76c47b --- /dev/null +++ b/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) diff --git a/stytch/consumer/models/fraud.py b/stytch/consumer/models/fraud.py index bf10a05..5cff1e4 100644 --- a/stytch/consumer/models/fraud.py +++ b/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: diff --git a/stytch/consumer/models/fraud_email.py b/stytch/consumer/models/fraud_email.py new file mode 100644 index 0000000..b9c406f --- /dev/null +++ b/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 diff --git a/stytch/version.py b/stytch/version.py index 217fb25..331dde6 100644 --- a/stytch/version.py +++ b/stytch/version.py @@ -1 +1 @@ -__version__ = "14.1.0" +__version__ = "14.2.0"