Merge pull request #13 from zerobounce/update/find-email-find-domain

Update/find email find domain

Author: vlungusst

.gitignore

@@ -60,3 +60,4 @@ docs/_build/
 target/
 \.idea/
 .vscode/
+.env

README.md

@@ -10,12 +10,39 @@ Import the sdk in your file:
 from zerobouncesdk import ZeroBounce
 ```
 
-Initialize the sdk with your api key:
+Initialize the SDK with your API key. You can optionally specify a base URL to use a different API region or a custom endpoint:
 
+**Default**: Uses the default ZeroBounce API endpoint
 ```python
+from zerobouncesdk import ZeroBounce
+
 zero_bounce = ZeroBounce("<YOUR_API_KEY>")
 ```
 
+**Using predefined API regions**: Use one of the available API regions
+```python
+from zerobouncesdk import ZeroBounce, ZBApiUrl
+
+# Use USA region
+zero_bounce = ZeroBounce("<YOUR_API_KEY>", base_url=ZBApiUrl.API_USA_URL)
+
+# Use EU region
+zero_bounce = ZeroBounce("<YOUR_API_KEY>", base_url=ZBApiUrl.API_EU_URL)
+
+# Use default region (explicit)
+zero_bounce = ZeroBounce("<YOUR_API_KEY>", base_url=ZBApiUrl.API_DEFAULT_URL)
+```
+
+**Using a custom URL string**: Provide your own base URL
+```python
+zero_bounce = ZeroBounce("<YOUR_API_KEY>", base_url="https://custom-api.example.com/v2")
+```
+
+**Available API regions:**
+- `ZBApiUrl.API_DEFAULT_URL` - Default ZeroBounce API (https://api.zerobounce.net/v2/)
+- `ZBApiUrl.API_USA_URL` - USA region API (https://api-us.zerobounce.net/v2/)
+- `ZBApiUrl.API_EU_URL` - EU region API (https://api-eu.zerobounce.net/v2/)
+
 #### Examples
 Then you can use any of the SDK methods, for example:
 
@@ -61,23 +88,89 @@ except ZBException as e:
     print("ZeroBounce get_activity error: " + str(e))
 ```
 
-* ####### Identify the correct email format when you provide a name and email domain
+* ####### Find the correct email format when you provide a name and email domain or company name
+
+```python
+from zerobouncesdk import ZeroBounce, ZBException
+
+zero_bounce = ZeroBounce("<YOUR_API_KEY>")
+
+# Option 1: Use find_email_format with domain
+domain = "example.com"  # The email domain for which to find the email format
+first_name = "John"      # The first name of the person whose email format is being searched
+middle_name = "Quill"    # Optional: The middle name of the person
+last_name = "Doe"        # Optional: The last name of the person
+
+try:
+    response = zero_bounce.find_email_format(
+        first_name=first_name,
+        domain=domain,
+        middle_name=middle_name,
+        last_name=last_name
+    )
+    print("Email: " + str(response.email))
+    print("Email Confidence: " + str(response.email_confidence))
+except ZBException as e:
+    print("ZeroBounce find_email_format error: " + str(e))
+```
+
+```python
+# Option 2: Use find_email_format with company_name
+from zerobouncesdk import ZeroBounce, ZBException
+
+zero_bounce = ZeroBounce("<YOUR_API_KEY>")
+
+company_name = "Acme Corp"  # The company name for which to find the email format
+first_name = "Jane"          # The first name of the person
+
+try:
+    response = zero_bounce.find_email_format(
+        first_name=first_name,
+        company_name=company_name
+    )
+    print("Email: " + str(response.email))
+    print("Domain: " + str(response.domain))
+    print("Company: " + str(response.company_name))
+except ZBException as e:
+    print("ZeroBounce find_email_format error: " + str(e))
+```
+
+```python
+# Option 3: Use find_domain to discover email formats for a domain
+from zerobouncesdk import ZeroBounce, ZBException
+
+zero_bounce = ZeroBounce("<YOUR_API_KEY>")
+
+domain = "example.com"  # The email domain to analyze
+
+try:
+    response = zero_bounce.find_domain(domain=domain)
+    print("Domain: " + str(response.domain))
+    print("Format: " + str(response.format))
+    print("Confidence: " + str(response.confidence))
+    print("Other formats: " + str(len(response.other_domain_formats)))
+except ZBException as e:
+    print("ZeroBounce find_domain error: " + str(e))
+```
 
 ```python
+# Option 4: Use find_domain with company_name
 from zerobouncesdk import ZeroBounce, ZBException
 
 zero_bounce = ZeroBounce("<YOUR_API_KEY>")
 
-domain = "example.com" # The email domain for which to find the email format
-first_name = "John" # The first name of the person whose email format is being searched
-middle_name = "Quill" # The middle name of the person whose email format is being searched
-last_name = "Doe" # The last name of the person whose email format is being searched
+company_name = "Acme Corp"  # The company name to analyze
 
 try:
-    response = zero_bounce.guess_format(domain, first_name, middle_name, last_name)
-    print("ZeroBounce guess format response: " + response)
+    response = zero_bounce.find_domain(company_name=company_name)
+    print("Domain: " + str(response.domain))
+    print("Company: " + str(response.company_name))
+    print("Format: " + str(response.format))
+    print("Confidence: " + str(response.confidence))
+    for fmt in response.other_domain_formats:
+        print(f"  Alternative: {fmt.format} (confidence: {fmt.confidence})")
 except ZBException as e:
-    print("ZeroBounce guess format error: " + str(e))
+    print("ZeroBounce find_domain error: " + str(e))
 ```
 
 * ####### Validate an email address

documentation.md

@@ -10,12 +10,39 @@ Importa el SDK en tu archivo:
 from zerobouncesdk import ZeroBounce
 ```
 
-Inicializa el SDK con tu clave de API:
+Inicializa el SDK con tu clave de API. Puedes opcionalmente especificar una URL base para usar una región de API diferente o un endpoint personalizado:
 
+**Por defecto**: Usa el endpoint predeterminado de ZeroBounce API
 ```python
+from zerobouncesdk import ZeroBounce
+
 zero_bounce = ZeroBounce("<TU_CLAVE_DE_API>")
 ```
 
+**Usando regiones de API predefinidas**: Usa una de las regiones de API disponibles
+```python
+from zerobouncesdk import ZeroBounce, ZBApiUrl
+
+# Usar región USA
+zero_bounce = ZeroBounce("<TU_CLAVE_DE_API>", base_url=ZBApiUrl.API_USA_URL)
+
+# Usar región EU
+zero_bounce = ZeroBounce("<TU_CLAVE_DE_API>", base_url=ZBApiUrl.API_EU_URL)
+
+# Usar región predeterminada (explícita)
+zero_bounce = ZeroBounce("<TU_CLAVE_DE_API>", base_url=ZBApiUrl.API_DEFAULT_URL)
+```
+
+**Usando una URL personalizada**: Proporciona tu propia URL base
+```python
+zero_bounce = ZeroBounce("<TU_CLAVE_DE_API>", base_url="https://custom-api.example.com/v2")
+```
+
+**Regiones de API disponibles:**
+- `ZBApiUrl.API_DEFAULT_URL` - API predeterminada de ZeroBounce (https://api.zerobounce.net/v2/)
+- `ZBApiUrl.API_USA_URL` - API de región USA (https://api-us.zerobounce.net/v2/)
+- `ZBApiUrl.API_EU_URL` - API de región EU (https://api-eu.zerobounce.net/v2/)
+
 #### Ejemplos
 Luego puedes utilizar cualquiera de los métodos del SDK, por ejemplo:
 
@@ -62,23 +89,89 @@ except ZBException as e:
 ```
 
 
-* ####### Identify the correct email format when you provide a name and email domain
+* ####### Encontrar el formato de correo electrónico correcto cuando proporcionas un nombre y un dominio o nombre de empresa
 
 ```python
 from zerobouncesdk import ZeroBounce, ZBException
 
-zero_bounce = ZeroBounce("<YOUR_API_KEY>")
+zero_bounce = ZeroBounce("<TU_CLAVE_DE_API>")
 
-domain = "example.com" # The email domain for which to find the email format
-first_name = "John" # The first name of the person whose email format is being searched
-middle_name = "Quill" # The middle name of the person whose email format is being searched
-last_name = "Doe" # The last name of the person whose email format is being searched
+# Opción 1: Usar find_email_format con dominio
+dominio = "example.com"  # El dominio de correo electrónico para encontrar el formato
+nombre = "John"          # El nombre de la persona cuyo formato de correo se está buscando
+segundo_nombre = "Quill"  # Opcional: El segundo nombre de la persona
+apellido = "Doe"          # Opcional: El apellido de la persona
 
 try:
-    response = zero_bounce.guess_format(domain, first_name, middle_name, last_name)
-    print("ZeroBounce guess format response: " + response)
+    response = zero_bounce.find_email_format(
+        first_name=nombre,
+        domain=dominio,
+        middle_name=segundo_nombre,
+        last_name=apellido
+    )
+    print("Correo: " + str(response.email))
+    print("Confianza del correo: " + str(response.email_confidence))
 except ZBException as e:
-    print("ZeroBounce guess format error: " + str(e))
+    print("Error de ZeroBounce find_email_format: " + str(e))
+```
+
+```python
+# Opción 2: Usar find_email_format con company_name
+from zerobouncesdk import ZeroBounce, ZBException
+
+zero_bounce = ZeroBounce("<TU_CLAVE_DE_API>")
+
+nombre_empresa = "Acme Corp"  # El nombre de la empresa para encontrar el formato de correo
+nombre = "Jane"                # El nombre de la persona
+
+try:
+    response = zero_bounce.find_email_format(
+        first_name=nombre,
+        company_name=nombre_empresa
+    )
+    print("Correo: " + str(response.email))
+    print("Dominio: " + str(response.domain))
+    print("Empresa: " + str(response.company_name))
+except ZBException as e:
+    print("Error de ZeroBounce find_email_format: " + str(e))
+```
+
+```python
+# Opción 3: Usar find_domain para descubrir formatos de correo para un dominio
+from zerobouncesdk import ZeroBounce, ZBException
+
+zero_bounce = ZeroBounce("<TU_CLAVE_DE_API>")
+
+dominio = "example.com"  # El dominio de correo electrónico a analizar
+
+try:
+    response = zero_bounce.find_domain(domain=dominio)
+    print("Dominio: " + str(response.domain))
+    print("Formato: " + str(response.format))
+    print("Confianza: " + str(response.confidence))
+    print("Otros formatos: " + str(len(response.other_domain_formats)))
+except ZBException as e:
+    print("Error de ZeroBounce find_domain: " + str(e))
+```
+
+```python
+# Opción 4: Usar find_domain con company_name
+from zerobouncesdk import ZeroBounce, ZBException
+
+zero_bounce = ZeroBounce("<TU_CLAVE_DE_API>")
+
+nombre_empresa = "Acme Corp"  # El nombre de la empresa a analizar
+
+try:
+    response = zero_bounce.find_domain(company_name=nombre_empresa)
+    print("Dominio: " + str(response.domain))
+    print("Empresa: " + str(response.company_name))
+    print("Formato: " + str(response.format))
+    print("Confianza: " + str(response.confidence))
+    for fmt in response.other_domain_formats:
+        print(f"  Alternativa: {fmt.format} (confianza: {fmt.confidence})")
+except ZBException as e:
+    print("Error de ZeroBounce find_domain: " + str(e))
 ```
 
 * ####### Validar una dirección de correo electrónico
@@ -272,3 +365,24 @@ try:
 except ZBException as e:
     print("ZeroBounce delete_file error: " + str(e))
 ```
+
+* ####### (Deprecado) Identificar el formato de correo electrónico correcto cuando proporcionas un nombre y un dominio de correo electrónico
+
+> **⚠️ Deprecado:** El método `guess_format` está deprecado y se eliminará en futuras versiones. Use `find_email_format` o `find_domain` en su lugar (vea los ejemplos arriba).
+
+```python
+from zerobouncesdk import ZeroBounce, ZBException
+
+zero_bounce = ZeroBounce("<TU_CLAVE_DE_API>")
+
+domain = "example.com" # El dominio de correo electrónico para encontrar el formato de correo
+first_name = "John" # El nombre de la persona cuyo formato de correo se está buscando
+middle_name = "Quill" # El segundo nombre de la persona cuyo formato de correo se está buscando
+last_name = "Doe" # El apellido de la persona cuyo formato de correo se está buscando
+
+try:
+    response = zero_bounce.guess_format(domain, first_name, middle_name, last_name)
+    print("ZeroBounce guess format response: " + response)
+except ZBException as e:
+    print("ZeroBounce guess format error: " + str(e))
+```

documentation_es.md

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zerobouncesdk"
-version = "1.1.2"
+version = "2.0.0"
 description = "ZeroBounce Python API - https://www.zerobounce.net."
 readme = "README.md"
 authors = [{ name = "ZeroBounce", email = "support@zerobounce.net" }]

pyproject.toml

@@ -1,3 +1,4 @@
+from .zb_api_url import ZBApiUrl
 from .zb_confidence import ZBConfidence
 from .zb_exceptions import ZBException, ZBApiException, ZBClientException
 from .zb_get_credits_response import ZBGetCreditsResponse
@@ -13,5 +14,7 @@
 from .zb_get_file_response import ZBGetFileResponse
 from .zb_delete_file_response import ZBDeleteFileResponse
 from .zb_guess_format_response import ZBGuessFormatResponse
+from .zb_find_email_format_response import ZBFindEmailFormatResponse
+from .zb_find_domain_response import ZBFindDomainResponse
 
 from .zerobouncesdk import ZeroBounce

src/zerobouncesdk/__init__.py

@@ -0,0 +1,10 @@
+from enum import Enum
+
+
+class ZBApiUrl(Enum):
+    """Enumeration of available ZeroBounce API base URLs."""
+    
+    API_DEFAULT_URL = "https://api.zerobounce.net/v2/"
+    API_USA_URL = "https://api-us.zerobounce.net/v2/"
+    API_EU_URL = "https://api-eu.zerobounce.net/v2/"
+

src/zerobouncesdk/zb_api_url.py

@@ -0,0 +1,44 @@
+from typing import List
+
+from . import ZBConfidence, ZBApiException
+from ._zb_response import ZBResponse
+from .zb_guess_format_response import ZBDomainFormat
+
+
+class ZBFindDomainResponse(ZBResponse):
+    """This is the response for the find_domain request."""
+
+    domain: str = None
+    """The domain that was used or found."""
+
+    company_name: str = None
+    """The company name that was used or found."""
+
+    format: str = None
+    """The guessed email format for the domain."""
+
+    confidence: ZBConfidence = None
+    """The confidence level for the guessed format."""
+
+    did_you_mean: str = None
+    """Suggestive fix for any input errors."""
+
+    failure_reason: str = None
+    """Reason for failure if the operation was unsuccessful."""
+
+    other_domain_formats: List[ZBDomainFormat] = []
+    """List of other possible domain formats with their confidence levels."""
+
+    def __init__(self, data):
+        super().__init__(data)
+        if "Message" in data or "message" in data:
+            message = data.get("message", data["Message"])
+            raise ZBApiException(message)
+
+        if self.confidence and isinstance(self.confidence, str):
+            self.confidence = ZBConfidence(self.confidence.lower())
+
+        self.other_domain_formats = [
+            ZBDomainFormat(df_data) for df_data in data.get("other_domain_formats", [])
+        ]
+