emailnator.asyncio package

Subpackages

• emailnator.asyncio.builders package
  • Subpackages
    • emailnator.asyncio.builders.helpers package
      • Submodules
      • emailnator.asyncio.builders.helpers.metaclass module
      • emailnator.asyncio.builders.helpers.xsrf_token_service module
      • Module contents
  • Submodules
  • emailnator.asyncio.builders.builders module
    • AsyncEmailnatorClient
      • AsyncEmailnatorClient._client
      • AsyncEmailnatorClient._xsrf_token
      • AsyncEmailnatorClient._headers
      • AsyncEmailnatorClient._initialized
      • AsyncEmailnatorClient.close()
      • AsyncEmailnatorClient.get_client()
      • AsyncEmailnatorClient.get_headers()
      • AsyncEmailnatorClient.get_xsrf_token()
      • AsyncEmailnatorClient.refresh_token()
  • Module contents
    • AsyncEmailnatorClient
      • AsyncEmailnatorClient._client
      • AsyncEmailnatorClient._xsrf_token
      • AsyncEmailnatorClient._headers
      • AsyncEmailnatorClient._initialized
      • AsyncEmailnatorClient.close()
      • AsyncEmailnatorClient.get_client()
      • AsyncEmailnatorClient.get_headers()
      • AsyncEmailnatorClient.get_xsrf_token()
      • AsyncEmailnatorClient.refresh_token()
• emailnator.asyncio.helpers package
  • Submodules
  • emailnator.asyncio.helpers.metaclass module
    • AsyncInitMeta
  • emailnator.asyncio.helpers.parser module
    • Parser
      • Parser.None
      • Parser.parse_email_response()
      • Parser.parse_message_response()
  • Module contents
    • AsyncInitMeta
    • Parser
      • Parser.None
      • Parser.parse_email_response()
      • Parser.parse_message_response()

Submodules

emailnator.asyncio.email_generator module

Asynchronous email generator module.

This module provides the AsyncEmailGenerator class, an asynchronous wrapper around the Emailnator API for working with temporary email addresses. It offers methods to:

• Generate a single temporary email address.

• Generate multiple temporary email addresses (limited to “100”, “200”, or “300”).

• Retrieve messages associated with a given email address.

Typical usage example:

from emailnator.asyncio.email_generator import AsyncEmailGenerator

async def main():

generator = AsyncEmailGenerator() email = await generator.generate_email() messages = await generator.get_messages(email) print(email, messages)

class emailnator.asyncio.email_generator.AsyncEmailGenerator(*args: Any, **kwargs: Any)

Bases: object

Asynchronous wrapper for generating temporary email addresses and retrieving their associated messages.

This class provides a high-level interface to the Emailnator API through asynchronous methods.

generators

Type:

Generators

- The underlying generator instance used to create email addresses.

message_getter

Type:

MessageGetter

- The instance responsible for retrieving messages linked to emails.

async generate_bulk_emails(emails_number='100')

Generate multiple email addresses asynchronously.

This method requests a batch of email addresses from the underlying Generators instance. The number of generated emails is restricted to specific supported values.

Parameters:

emails_number (Literal["100", "200", "300"], optional) – The number of email addresses to generate. Must be one of: “100”, “200”, or “300”. Defaults to “100”.

Returns:

A list of newly generated email addresses.

Return type:

list[str]

Raises:

• ValueError – If emails_number is not one of the supported values.

• RuntimeError – If the generator fails to return a valid list of emails.

async generate_email()

Generate a new email address asynchronously.

This method requests a new email address from the underlying Generators instance and returns the first generated address.

Returns:

A newly generated email address.

Return type:

str

Raises:

RuntimeError – If the generator fails to return at least one email.

async get_message(email, message_id)

Asynchronously retrieve the full content of a specific email message.

This coroutine validates its inputs, delegates the retrieval to the underlying message getter, and returns the message body as a string (typically HTML or plain text).

Parameters:

• email (str) – The email address associated with the message.

• message_id (str) – The unique identifier of the message to fetch.

Returns:

The content of the message, usually in HTML or plain text format.

Return type:

str

Raises:

• ValueError – If the email or message_id is invalid or empty.

• RuntimeError – If message retrieval fails.

async get_message_from_sender(sender, email)

Retrieves the full text of the first message sent by a specific sender to a given email.

Parameters:

• sender (str) – Email address or name of the sender to search for. Must be a non-empty string.

• email (str) – The target email address. Must be a non-empty string.

Returns:

The full message text if a message from the specified sender is found, otherwise None.

Return type:

str | None

Raises:

• ValueError – If sender or email is invalid.

• RuntimeError – If fetching messages or message text fails.

async get_messages(email)

Asynchronously retrieve all messages associated with the given email address.

This coroutine validates the email address, delegates the retrieval to the underlying MessageGetter instance, and returns a list of message metadata dictionaries.

Parameters:

email (str) – The email address for which to fetch messages.

Returns:

A list of message dictionaries, each typically containing keys such as ‘messageID’, ‘from’, ‘subject’, and ‘time’.

Return type:

list[dict[str, str]]

Raises:

• ValueError – If the provided email address is invalid or empty.

• RuntimeError – If message retrieval fails or the response is invalid.

async parse_message_from_sender(messages, sender)

Parses a list of messages and retrieves the messageID of a message sent by a specific sender.

Parameters:

• messages (list[dict[str, str]]) – List of messages, each being a dictionary with at least ‘from’ and ‘messageID’ keys.

• sender (str) – Email address or name of the sender to search for. Must be a non-empty string.

Returns:

The messageID if a message from the specified sender is found, otherwise None.

Return type:

str | None

Raises:

ValueError – If messages is not a list of dicts or if sender is invalid.

emailnator.asyncio.generators module

EmailNator API Client

This module provides a wrapper around the EmailNator API, facilitating the generation of single or bulk email addresses. It includes utility functions for handling HTTP requests and parsing JSON responses.

Typical Usage Example:

from emailnator_client import Generators generator = Generators() await generator.generate_email() [‘example@gmail.com’] await generator.generate_bulk_emails(

options=[‘dotGmail’, ‘plusGmail’], ‘5’

) [‘example1@gmail.com’, ‘example2@gmail.com’, ‘example3@gmail.com’, ‘example4@gmail.com’, ‘example5@gmail.com’]

class emailnator.asyncio.generators.Generators(*args: Any, **kwargs: Any)

Bases: object

Wrapper for interacting with the EmailNator API to generate emails.

This class provides methods for generating single or multiple email addresses using the EmailNator API. It manages the HTTP client, default headers, and helper functions for parsing API responses.

parser

Parser for processing data.

Type:

Parser

client

Asynchronous HTTP client.

Type:

httpx.AsyncClient

headers

HTTP headers for requests.

Type:

dict

async generate_bulk_emails(emails_number='100', options=['dotGmail', 'plusGmail'], base_url='https://www.emailnator.com')

Generate multiple email addresses via the API.

Sends a POST request to the /generate-email endpoint with the provided options and the number of emails to generate. Uses parse_json_response to validate the response and return the parsed JSON.

Parameters:

• emails_number (Literal["100", "200", "300"], optional) – Number of emails to generate. Defaults to “100”.

• options (list[str]) – A list of options to customize email generation.

• base_url (str, optional) – Base URL of the API. Defaults to config.BASE_URL.

Returns:

A writed JSON response containing generated emails.

Return type:

list[str]

Raises:

RuntimeError – If the API response indicates an error or is not valid JSON.

async generate_email(options=['dotGmail', 'plusGmail'], base_url='https://www.emailnator.com')

Generate a single email address via the API.

Sends a POST request to the /generate-email endpoint with default Gmail options (from config.GMAIL_CONFIG). Uses parse_json_response to validate the response and return the parsed JSON.

Parameters:

• options (list[str]) – A list of options to customize email generation.

• base_url (str, optional) – Base URL of the API. Defaults to config.BASE_URL.

Returns:

A writed JSON response containing the generated email.

Return type:

list[str]

Raises:

RuntimeError – If the API response indicates an error (status != 200) or if the response is not valid JSON.

emailnator.asyncio.message_getter module

Module for interacting with the EmailNator API to retrieve email messages.

This module provides the MessageGetter class, which is a wrapper around the EmailNator API for fetching email messages. It uses an HTTP client from httpx and helper utilities from Helpers to parse API responses.

class emailnator.asyncio.message_getter.MessageGetter(*args: Any, **kwargs: Any)

Bases: object

Asynchronous client wrapper for retrieving messages from the EmailNator API.

This class provides functionality to fetch the list of messages associated with a given email address and parse the results using the Parser utility.

parser

Parser instance used to process API responses.

Type:

Parser

client

Asynchronous HTTP client for making requests to the EmailNator API.

Type:

httpx.AsyncClient

headers

Default HTTP headers applied to all requests.

Type:

dict[str, str]

async get_message(email, message_id, base_url='https://www.emailnator.com')

Asynchronously retrieve the full content of a specific email message from the API.

This coroutine sends a POST request to the /message-list endpoint with the given email and message ID, and returns the raw response text (typically the HTML content of the message).

Parameters:

• email (str) – The email address from which to retrieve the message.

• message_id (str) – The unique identifier of the message to fetch.

• base_url (str, optional) – The base URL of the API. Defaults to config.BASE_URL.

Returns:

The raw message content as returned by the server (usually HTML).

Return type:

str

Raises:

• AssertionError – If the HTTP client (self.client) is not initialized.

• httpx.RequestError – If there is a network or connection issue.

• httpx.HTTPStatusError – If the response status code indicates an error.

async get_message_list(email, base_url='https://www.emailnator.com')

Asynchronously retrieve a list of messages associated with the given email address.

This coroutine sends a POST request to the /message-list endpoint to fetch metadata about messages linked to the specified email. The result is parsed and returned as a list of message dictionaries.

Parameters:

• email (str) – The email address for which to fetch the message list.

• base_url (str, optional) – The base URL of the API. Defaults to config.BASE_URL.

Returns:

A list of message metadata dictionaries. Each dictionary typically contains keys such as ‘messageID’, ‘from’, ‘subject’, and ‘time’.

Return type:

list[dict[str, str]]

Raises:

• AssertionError – If the HTTP client (self.client) is not initialized.

• httpx.RequestError – If a network-related error occurs.

• httpx.HTTPStatusError – If the HTTP response indicates a failed request.

• RuntimeError – If the response cannot be parsed or is missing expected data.

Module contents

class emailnator.asyncio.Generators(*args: Any, **kwargs: Any)

Bases: object

Wrapper for interacting with the EmailNator API to generate emails.

This class provides methods for generating single or multiple email addresses using the EmailNator API. It manages the HTTP client, default headers, and helper functions for parsing API responses.

parser

Parser for processing data.

Type:

Parser

client

Asynchronous HTTP client.

Type:

httpx.AsyncClient

headers

HTTP headers for requests.

Type:

dict

async generate_bulk_emails(emails_number='100', options=['dotGmail', 'plusGmail'], base_url='https://www.emailnator.com')

Generate multiple email addresses via the API.

Sends a POST request to the /generate-email endpoint with the provided options and the number of emails to generate. Uses parse_json_response to validate the response and return the parsed JSON.

Parameters:

• emails_number (Literal["100", "200", "300"], optional) – Number of emails to generate. Defaults to “100”.

• options (list[str]) – A list of options to customize email generation.

• base_url (str, optional) – Base URL of the API. Defaults to config.BASE_URL.

Returns:

A writed JSON response containing generated emails.

Return type:

list[str]

Raises:

RuntimeError – If the API response indicates an error or is not valid JSON.

async generate_email(options=['dotGmail', 'plusGmail'], base_url='https://www.emailnator.com')

Generate a single email address via the API.

Sends a POST request to the /generate-email endpoint with default Gmail options (from config.GMAIL_CONFIG). Uses parse_json_response to validate the response and return the parsed JSON.

Parameters:

• options (list[str]) – A list of options to customize email generation.

• base_url (str, optional) – Base URL of the API. Defaults to config.BASE_URL.

Returns:

A writed JSON response containing the generated email.

Return type:

list[str]

Raises:

RuntimeError – If the API response indicates an error (status != 200) or if the response is not valid JSON.

class emailnator.asyncio.MessageGetter(*args: Any, **kwargs: Any)

Bases: object

Asynchronous client wrapper for retrieving messages from the EmailNator API.

This class provides functionality to fetch the list of messages associated with a given email address and parse the results using the Parser utility.

parser

Parser instance used to process API responses.

Type:

Parser

client

Asynchronous HTTP client for making requests to the EmailNator API.

Type:

httpx.AsyncClient

headers

Default HTTP headers applied to all requests.

Type:

dict[str, str]

async get_message(email, message_id, base_url='https://www.emailnator.com')

Asynchronously retrieve the full content of a specific email message from the API.

This coroutine sends a POST request to the /message-list endpoint with the given email and message ID, and returns the raw response text (typically the HTML content of the message).

Parameters:

• email (str) – The email address from which to retrieve the message.

• message_id (str) – The unique identifier of the message to fetch.

• base_url (str, optional) – The base URL of the API. Defaults to config.BASE_URL.

Returns:

The raw message content as returned by the server (usually HTML).

Return type:

str

Raises:

• AssertionError – If the HTTP client (self.client) is not initialized.

• httpx.RequestError – If there is a network or connection issue.

• httpx.HTTPStatusError – If the response status code indicates an error.

async get_message_list(email, base_url='https://www.emailnator.com')

Asynchronously retrieve a list of messages associated with the given email address.

This coroutine sends a POST request to the /message-list endpoint to fetch metadata about messages linked to the specified email. The result is parsed and returned as a list of message dictionaries.

Parameters:

• email (str) – The email address for which to fetch the message list.

• base_url (str, optional) – The base URL of the API. Defaults to config.BASE_URL.

Returns:

A list of message metadata dictionaries. Each dictionary typically contains keys such as ‘messageID’, ‘from’, ‘subject’, and ‘time’.

Return type:

list[dict[str, str]]

Raises:

• AssertionError – If the HTTP client (self.client) is not initialized.

• httpx.RequestError – If a network-related error occurs.

• httpx.HTTPStatusError – If the HTTP response indicates a failed request.

• RuntimeError – If the response cannot be parsed or is missing expected data.