From 1a3cdf28ad4b110a50b05ae9f5660f3440442e79 Mon Sep 17 00:00:00 2001 From: Jon M Date: Wed, 27 May 2026 08:41:13 +0100 Subject: [PATCH 1/2] Improve intelliSense hints --- mailosaur/mailosaur_client.py | 32 ++++- mailosaur/operations/analysis_operations.py | 28 ++-- mailosaur/operations/devices_operations.py | 52 ++++--- mailosaur/operations/files_operations.py | 44 +++--- mailosaur/operations/messages_operations.py | 150 +++++++++----------- mailosaur/operations/previews_operations.py | 10 +- mailosaur/operations/servers_operations.py | 80 +++++------ mailosaur/operations/usage_operations.py | 17 ++- 8 files changed, 195 insertions(+), 218 deletions(-) diff --git a/mailosaur/mailosaur_client.py b/mailosaur/mailosaur_client.py index 3488595..11a04f0 100644 --- a/mailosaur/mailosaur_client.py +++ b/mailosaur/mailosaur_client.py @@ -23,10 +23,38 @@ class MailosaurClient(object): - """ Main class to access Mailosaur.com api. """ + """The Mailosaur client - the main entry point to the Mailosaur API. + + Construct an instance with your API key (or set the ``MAILOSAUR_API_KEY`` + environment variable), then use the operations namespaces (``messages``, + ``servers``, ``files``, ``devices``, ``analysis``, ``previews``, ``usage``) + to automate email and SMS testing. + + :ivar analysis: Operations for analyzing email content and deliverability, including spam scoring. + :vartype analysis: ~mailosaur.operations.analysis_operations.AnalysisOperations + :ivar files: Operations for downloading attachments, EML source, and email preview screenshots. + :vartype files: ~mailosaur.operations.files_operations.FilesOperations + :ivar messages: Operations for finding, retrieving, creating, and managing email and SMS messages. + :vartype messages: ~mailosaur.operations.messages_operations.MessagesOperations + :ivar servers: Operations for creating and managing your Mailosaur servers (virtual inboxes). + :vartype servers: ~mailosaur.operations.servers_operations.ServersOperations + :ivar usage: Operations for inspecting account usage limits and recent transactional usage. + :vartype usage: ~mailosaur.operations.usage_operations.UsageOperations + :ivar devices: Operations for managing virtual security devices and retrieving their one-time passwords. + :vartype devices: ~mailosaur.operations.devices_operations.DevicesOperations + :ivar previews: Operations for discovering the email clients available for generating email previews. + :vartype previews: ~mailosaur.operations.previews_operations.PreviewsOperations + """ def __init__(self, api_key=None, base_url="https://mailosaur.com/"): - """ Pass in your mailbox id and api key to authenticate """ + """Returns an instance of the Mailosaur client. + + :param api_key: Optional API key. Overrides the MAILOSAUR_API_KEY + environment variable if set. + :type api_key: str + :param base_url: Optionally overrides the base URL of the Mailosaur service. + :type base_url: str + """ api_key = api_key or os.environ.get('MAILOSAUR_API_KEY') if not api_key: diff --git a/mailosaur/operations/analysis_operations.py b/mailosaur/operations/analysis_operations.py index 7864eb8..ccc09b7 100644 --- a/mailosaur/operations/analysis_operations.py +++ b/mailosaur/operations/analysis_operations.py @@ -3,7 +3,9 @@ from ..models import DeliverabilityReport class AnalysisOperations(object): - """AnalysisOperations operations. + """Operations for analyzing the content and deliverability of an email, including + SpamAssassin scoring and per-provider deliverability reports. + Accessed via ``client.analysis``. """ def __init__(self, session, base_url, handle_http_error): @@ -12,16 +14,12 @@ def __init__(self, session, base_url, handle_http_error): self.handle_http_error = handle_http_error def spam(self, email): - """Perform a spam test. + """Perform a spam analysis of an email. - Perform spam testing on the specified email. - - :param email: The identifier of the email to be analyzed. - :type email: str - :return: SpamAnalysisResult + :param email: The identifier of the message to be analyzed. + :type email: str + :return: A result containing the spam score and filter results. :rtype: ~mailosaur.models.SpamAnalysisResult - :raises: - :class:`MailosaurException` """ url = "%sapi/analysis/spam/%s" % (self.base_url, email) response = self.session.get(url) @@ -35,16 +33,12 @@ def spam(self, email): return SpamAnalysisResult(data) def deliverability(self, email): - """Perform a deliverability test. - - Perform deliverability testing on the specified email. + """Perform a deliverability report of an email. - :param email: The identifier of the email to be analyzed. - :type email: str - :return: DeliverabilityReport + :param email: The identifier of the message to be analyzed. + :type email: str + :return: A deliverability report for the email. :rtype: ~mailosaur.models.DeliverabilityReport - :raises: - :class:`MailosaurException` """ url = "%sapi/analysis/deliverability/%s" % (self.base_url, email) response = self.session.get(url) diff --git a/mailosaur/operations/devices_operations.py b/mailosaur/operations/devices_operations.py index 07c375e..6c167c8 100644 --- a/mailosaur/operations/devices_operations.py +++ b/mailosaur/operations/devices_operations.py @@ -10,7 +10,9 @@ class DevicesOperations(object): - """DevicesOperations operations. + """Operations for managing virtual security devices and retrieving their current + one-time passwords (OTPs), used to automate testing of app-based multi-factor + authentication. Accessed via ``client.devices``. """ def __init__(self, session, base_url, handle_http_error): @@ -19,20 +21,24 @@ def __init__(self, session, base_url, handle_http_error): self.handle_http_error = handle_http_error def generate_email_address(self, server): + """Generates a random email address by appending a random string in front of + the server's domain name. + + :param server: The identifier of the server. + :type server: str + :return: A random email address ending in the server's domain. + :rtype: str + """ host = os.getenv('MAILOSAUR_SMTP_HOST', 'mailosaur.net') randomString = ''.join(random.choice( string.ascii_uppercase + string.digits) for _ in range(10)) return "%s@%s.%s" % (randomString, server, host) def list(self): - """List all devices. - - Returns a list of your virtual security devices. + """Returns a list of your virtual security devices. - :return: DeviceListResult + :return: A result containing your devices. :rtype: ~mailosaur.models.DeviceListResult - :raises: - :class:`MailosaurException` """ url = "%sapi/devices" % (self.base_url) response = self.session.get(url) @@ -46,16 +52,12 @@ def list(self): return DeviceListResult(data) def create(self, device_create_options): - """Create a device. + """Creates a new virtual security device. - Creates a new virtual security device and returns it. - - :param device_create_options: + :param device_create_options: Options used to create a new Mailosaur virtual security device. :type device_create_options: ~mailosaur.models.DeviceCreateOptions - :return: Device + :return: The newly-created device. :rtype: ~mailosaur.models.Device - :raises: - :class:`MailosaurException` """ url = "%sapi/devices" % (self.base_url) response = self.session.post(url, json=device_create_options.to_json()) @@ -69,17 +71,13 @@ def create(self, device_create_options): return Device(data) def otp(self, query): - """Retrieves the current one-time password for a saved device, or given base32-encoded shared secret. - - Retrieves the detail for a single server. Simply supply the unique - identifier for the required server. + """Retrieves the current one-time password for a saved device, or given + base32-encoded shared secret. :param query: Either the unique identifier of the device, or a base32-encoded shared secret. - :type query: str - :return: OtpResult + :type query: str + :return: A result containing the current one-time password. :rtype: ~mailosaur.models.OtpResult - :raises: - :class:`MailosaurException` """ if "-" in query: url = "%sapi/devices/%s/otp" % (self.base_url, query) @@ -106,16 +104,14 @@ def otp(self, query): def delete( self, id): - """Delete a device. + """Permanently delete a virtual security device. - Permanently delete a virtual security device. This operation cannot be undone. + This operation cannot be undone. - :param id: The identifier of the device to be deleted. - :type id: str + :param id: The unique identifier of the device. + :type id: str :return: None :rtype: None - :raises: - :class:`MailosaurException` """ url = "%sapi/devices/%s" % (self.base_url, id) response = self.session.delete(url) diff --git a/mailosaur/operations/files_operations.py b/mailosaur/operations/files_operations.py index 29024dc..33bf1e6 100644 --- a/mailosaur/operations/files_operations.py +++ b/mailosaur/operations/files_operations.py @@ -4,7 +4,9 @@ class FilesOperations(object): - """FilesOperations operations. + """Operations for downloading the raw content associated with a message - file + attachments, the full EML source of an email, and rendered email previews. + Accessed via ``client.files``. """ def __init__(self, session, base_url, handle_http_error): @@ -13,17 +15,12 @@ def __init__(self, session, base_url, handle_http_error): self.handle_http_error = handle_http_error def get_attachment(self, id): - """Download an attachment. + """Downloads a single attachment. - Downloads a single attachment. Simply supply the unique identifier for - the required attachment. - - :param id: The identifier of the attachment to be downloaded. + :param id: The identifier for the required attachment. :type id: str - :return: object - :rtype: Generator - :raises: - :class:`HttpOperationError` + :return: A streamed response whose body contains the attachment's binary content. + :rtype: ~requests.Response """ url = "%sapi/files/attachments/%s" % (self.base_url, id) response = self.session.get(url, stream=True) @@ -35,17 +32,12 @@ def get_attachment(self, id): return response def get_email(self, id): - """Download EML. - - Downloads an EML file representing the specified email. Simply supply - the unique identifier for the required email. + """Downloads an EML file representing the specified email. - :param id: The identifier of the email to be downloaded. + :param id: The identifier for the required message. :type id: str - :return: object - :rtype: Generator - :raises: - :class:`HttpOperationError` + :return: A streamed response whose body contains the raw EML content of the email. + :rtype: ~requests.Response """ url = "%sapi/files/email/%s" % (self.base_url, id) response = self.session.get(url, stream=True) @@ -57,17 +49,17 @@ def get_email(self, id): return response def get_preview(self, id): - """Download an email preview. + """Downloads a screenshot of your email rendered in a real email client. - Downloads a screenshot of your email rendered in a real email client. Simply supply - the unique identifier for the required preview. + Simply supply the unique identifier for the required preview. :param id: The identifier of the email preview to be downloaded. :type id: str - :return: object - :rtype: Generator - :raises: - :class:`HttpOperationError` + :return: A streamed response whose body contains the preview screenshot image. + :rtype: ~requests.Response + :raises: :class:`MailosaurException` + with error type ``preview_timeout`` if the preview is not generated + within the time limit. """ timeout = 120000 poll_count = 0 diff --git a/mailosaur/operations/messages_operations.py b/mailosaur/operations/messages_operations.py index 7513cde..0e08cf6 100644 --- a/mailosaur/operations/messages_operations.py +++ b/mailosaur/operations/messages_operations.py @@ -7,7 +7,9 @@ class MessagesOperations(object): - """MessagesOperations operations. + """Operations for finding, retrieving, creating, forwarding, replying to, and + deleting the email and SMS messages received by your Mailosaur servers. + Accessed via ``client.messages``. """ def __init__(self, session, base_url, handle_http_error): @@ -16,15 +18,16 @@ def __init__(self, session, base_url, handle_http_error): self.handle_http_error = handle_http_error def get(self, server, criteria, timeout=10000, received_after=(datetime.today() - timedelta(hours=1)), dir=None): - """Retrieve a message using search criteria. + """Waits for a message to be found, returning as soon as a message matching the + specified search criteria is found. - Returns as soon as a message matching the specified search criteria is - found. This is the most efficient method of looking up a message. + **Recommended:** This is the most efficient method of looking up a message, + therefore we recommend using it wherever possible. - :param server: The identifier of the server hosting the message. + :param server: The unique identifier of the containing server. :type server: str - :param criteria: The search criteria to use in order to find a match. - :type criteria: ~mailosaur.models.SearchCriteria + :param criteria: The criteria with which to find messages during a search. + :type criteria: ~mailosaur.models.SearchCriteria :param timeout: Specify how long to wait for a matching result (in milliseconds). :type timeout: int :param received_after: Limits results to only messages received after this date/time. @@ -32,10 +35,11 @@ def get(self, server, criteria, timeout=10000, received_after=(datetime.today() :param dir: Optionally limits results based on the direction (`Sent` or `Received`), with the default being `Received`. :type dir: str - :return: Message + :return: The first message matching the criteria. :rtype: ~mailosaur.models.Message - :raises: - :class:`MailosaurException` + :raises: :class:`MailosaurException` + with error type ``no_messages_found`` if no matching message exists, or + ``search_timeout`` if no matching message arrives before the timeout elapses. """ # Defaults timeout to 10s, receivedAfter to 1h if len(server) != 8: @@ -47,17 +51,15 @@ def get(self, server, criteria, timeout=10000, received_after=(datetime.today() return self.get_by_id(result.items[0].id) def get_by_id(self, id): - """Retrieve a message. + """Retrieves the detail for a single message. - Retrieves the detail for a single email message. Simply supply the + Must be used in conjunction with either list or search in order to get the unique identifier for the required message. - :param id: The identifier of the email message to be retrieved. - :type id: str - :return: Message + :param id: The unique identifier of the message to be retrieved. + :type id: str + :return: The full message. :rtype: ~mailosaur.models.Message - :raises: - :class:`MailosaurException` """ url = "%sapi/messages/%s" % (self.base_url, id) response = self.session.get(url) @@ -71,17 +73,15 @@ def get_by_id(self, id): return Message(data) def delete(self, id): - """Delete a message. + """Permanently deletes a message. - Permanently deletes a message. This operation cannot be undone. Also - deletes any attachments related to the message. + Also deletes any attachments related to the message. This operation cannot + be undone. - :param id: The identifier of the message to be deleted. - :type id: str + :param id: The identifier for the message. + :type id: str :return: None :rtype: None - :raises: - :class:`MailosaurException` """ url = "%sapi/messages/%s" % (self.base_url, id) response = self.session.delete(url) @@ -91,29 +91,26 @@ def delete(self, id): return def list(self, server, page=None, items_per_page=None, received_after=None, dir=None): - """List all messages. + """Returns a list of your messages in summary form. - Returns a list of your messages in summary form. The summaries are - returned sorted by received date, with the most recently-received - messages appearing first. + The summaries are returned sorted by received date, with the most + recently-received messages appearing first. - :param server: The identifier of the server hosting the messages. + :param server: The unique identifier of the required server. :type server: str :param page: Used in conjunction with `itemsPerPage` to support pagination. :type page: int :param items_per_page: A limit on the number of results to be returned per page. Can be set between 1 and 1000 items, the default is 50. - :type items_per_page: int + :type items_per_page: int :param received_after: Limits results to only messages received after this date/time. :type received_after: datetime :param dir: Optionally limits results based on the direction (`Sent` or `Received`), with the default being `Received`. :type dir: str - :return: MessageListResult + :return: A result containing the message summaries. :rtype: ~mailosaur.models.MessageListResult - :raises: - :class:`MailosaurException` """ url = "%sapi/messages" % (self.base_url) @@ -133,18 +130,14 @@ def list(self, server, page=None, items_per_page=None, received_after=None, dir= return MessageListResult(data) def delete_all(self, server): - """Delete all messages. + """Permanently delete all messages within a server. - Permanently deletes all messages held by the specified server. This - operation cannot be undone. Also deletes any attachments related to - each message. + This operation cannot be undone. - :param server: The identifier of the server to be emptied. - :type server: str + :param server: The unique identifier of the server. + :type server: str :return: None :rtype: None - :raises: - :class:`MailosaurException` """ url = "%sapi/messages" % (self.base_url) params = {'server': server} @@ -155,15 +148,14 @@ def delete_all(self, server): return def search(self, server, criteria, page=None, items_per_page=None, timeout=None, received_after=None, error_on_timeout=True, dir=None): - """Search for messages. + """Returns a list of messages matching the specified search criteria, in summary form. - Returns a list of messages matching the specified search criteria, in - summary form. The messages are returned sorted by received date, with - the most recently-received messages appearing first. + The messages are returned sorted by received date, with the most + recently-received messages appearing first. - :param server: The identifier of the server hosting the messages. + :param server: The unique identifier of the server to search. :type server: str - :param criteria: The search criteria to match results against. + :param criteria: The criteria with which to find messages during a search. :type criteria: ~mailosaur.models.SearchCriteria :param page: Used in conjunction with `itemsPerPage` to support pagination. @@ -175,16 +167,17 @@ def search(self, server, criteria, page=None, items_per_page=None, timeout=None, :type timeout: int :param received_after: Limits results to only messages received after this date/time. :type received_after: datetime - :param error_on_timeout: When set to false, an error will not be throw if timeout + :param error_on_timeout: When set to false, an error will not be thrown if timeout is reached (default: true). :type error_on_timeout: bool :param dir: Optionally limits results based on the direction (`Sent` or `Received`), with the default being `Received`. :type dir: str - :return: MessageListResult + :return: A result containing the matching message summaries. :rtype: ~mailosaur.models.MessageListResult - :raises: - :class:`MailosaurException` + :raises: :class:`MailosaurException` + with error type ``search_timeout`` if no matching message is found before + the timeout elapses, unless ``error_on_timeout`` is set to false. """ url = "%sapi/messages/search" % (self.base_url) @@ -233,20 +226,17 @@ def search(self, server, criteria, page=None, items_per_page=None, timeout=None, time.sleep(delay / 1000) def create(self, server, options): - """Create a message. + """Creates a new message that can be sent to a verified email address. - Creates a new message that can be sent to a verified email address. This is - useful in scenarios where you want an email to trigger a workflow in your - product + This is useful in scenarios where you want an email to trigger a workflow + in your product. - :param server: The identifier of the server to create the message in. + :param server: The unique identifier of the required server. :type server: str - :param options: The options with which to create the message. + :param options: Options to use when creating a new message. :type options: ~mailosaur.models.MessageCreateOptions - :return: None - :rtype: None - :raises: - :class:`MailosaurException` + :return: The newly-created message. + :rtype: ~mailosaur.models.Message """ url = "%sapi/messages" % (self.base_url) params = {'server': server} @@ -262,18 +252,16 @@ def create(self, server, options): return Message(data) def forward(self, id, options): - """Forward an email. + """Forwards the specified message to a verified email address. - Forwards the specified email to a verified email address. + This is useful for simulating a user forwarding one of your email messages. - :param id: The identifier of the email to forward. + :param id: The unique identifier of the message to be forwarded. :type id: str - :param options: The options with which to forward the email. + :param options: Options to use when forwarding a message. :type options: ~mailosaur.models.MessageForwardOptions - :return: None - :rtype: None - :raises: - :class:`MailosaurException` + :return: The forwarded message. + :rtype: ~mailosaur.models.Message """ url = "%sapi/messages/%s/forward" % (self.base_url, id) response = self.session.post(url, json=options.to_json()) @@ -287,19 +275,17 @@ def forward(self, id, options): return Message(data) def reply(self, id, options): - """Reply to an email. + """Sends a reply to the specified message. - Sends a reply to the specified email. This is useful for when simulating a user - replying to one of your emails. + This is useful for when simulating a user replying to one of your email + or SMS messages. - :param id: The identifier of the email to reply to. + :param id: The unique identifier of the message to be replied to. :type id: str - :param options: The options with which to reply to the email. + :param options: Options to use when replying to a message. :type options: ~mailosaur.models.MessageReplyOptions - :return: None - :rtype: None - :raises: - :class:`MailosaurException` + :return: The reply message. + :rtype: ~mailosaur.models.Message """ url = "%sapi/messages/%s/reply" % (self.base_url, id) response = self.session.post(url, json=options.to_json()) @@ -313,18 +299,14 @@ def reply(self, id, options): return Message(data) def generate_previews(self, id, options): - """Generate email previews. - - Generates screenshots of an email rendered in the specified email clients. + """Generates screenshots of an email rendered in the specified email clients. :param id: The identifier of the email to preview. :type id: str :param options: The options with which to generate previews. :type options: ~mailosaur.models.PreviewRequestOptions - :return: PreviewListResult + :return: A result containing the generated previews. :rtype: ~mailosaur.models.PreviewListResult - :raises: - :class:`MailosaurException` """ url = "%sapi/messages/%s/screenshots" % (self.base_url, id) response = self.session.post(url, json=options.to_json()) diff --git a/mailosaur/operations/previews_operations.py b/mailosaur/operations/previews_operations.py index 20e7006..931f9f9 100644 --- a/mailosaur/operations/previews_operations.py +++ b/mailosaur/operations/previews_operations.py @@ -2,7 +2,9 @@ class PreviewsOperations(object): - """PreviewsOperations operations. + """Operations for discovering the email clients available for generating email + previews (screenshots of an email rendered in real clients). + Accessed via ``client.previews``. """ def __init__(self, session, base_url, handle_http_error): @@ -13,12 +15,8 @@ def __init__(self, session, base_url, handle_http_error): def list_email_clients(self): """List all email clients that can be used to generate email previews. - Returns a list of available email clients. - - :return: EmailClientListResult + :return: A result containing the available email clients. :rtype: ~mailosaur.models.EmailClientListResult - :raises: - :class:`MailosaurException` """ url = "%sapi/screenshots/clients" % (self.base_url) response = self.session.get(url) diff --git a/mailosaur/operations/servers_operations.py b/mailosaur/operations/servers_operations.py index 1232773..9fc331d 100644 --- a/mailosaur/operations/servers_operations.py +++ b/mailosaur/operations/servers_operations.py @@ -6,7 +6,9 @@ from ..models import MailosaurException class ServersOperations(object): - """ServersOperations operations. + """Operations for creating and managing your Mailosaur servers - the virtual + inboxes that group your tests together, each with its own domain and + SMTP/POP3/IMAP credentials. Accessed via ``client.servers``. """ def __init__(self, session, base_url, handle_http_error): @@ -15,20 +17,25 @@ def __init__(self, session, base_url, handle_http_error): self.handle_http_error = handle_http_error def generate_email_address(self, server): + """Generates a random email address by appending a random string in front of + the server's domain name. + + :param server: The identifier of the server. + :type server: str + :return: A random email address ending in the server's domain. + :rtype: str + """ host = os.getenv('MAILOSAUR_SMTP_HOST', 'mailosaur.net') randomString = ''.join(random.choice(string.ascii_uppercase + string.digits) for _ in range(10)) return "%s@%s.%s" % (randomString, server, host) def list(self): - """List all servers. + """Returns a list of your virtual servers. - Returns a list of your virtual SMTP servers. Servers are returned - sorted in alphabetical order. + Servers are returned sorted in alphabetical order. - :return: ServerListResult + :return: A result containing your servers. :rtype: ~mailosaur.models.ServerListResult - :raises: - :class:`MailosaurException` """ url = "%sapi/servers" % (self.base_url) response = self.session.get(url) @@ -42,16 +49,12 @@ def list(self): return ServerListResult(data) def create(self, server_create_options): - """Create a server. - - Creates a new virtual SMTP server and returns it. + """Creates a new virtual server. - :param server_create_options: + :param server_create_options: Options used to create a new Mailosaur server. :type server_create_options: ~mailosaur.models.ServerCreateOptions - :return: Server + :return: The newly-created server. :rtype: ~mailosaur.models.Server - :raises: - :class:`MailosaurException` """ url = "%sapi/servers" % (self.base_url) response = self.session.post(url, json=server_create_options.to_json()) @@ -65,17 +68,12 @@ def create(self, server_create_options): return Server(data) def get(self, id): - """Retrieve a server. + """Retrieves the detail for a single server. - Retrieves the detail for a single server. Simply supply the unique - identifier for the required server. - - :param id: The identifier of the server to be retrieved. - :type id: str - :return: Server + :param id: The unique identifier of the server. + :type id: str + :return: The server. :rtype: ~mailosaur.models.Server - :raises: - :class:`MailosaurException` """ url = "%sapi/servers/%s" % (self.base_url, id) response = self.session.get(url) @@ -89,17 +87,14 @@ def get(self, id): return Server(data) def get_password(self, id): - """Retrieve server password. + """Retrieves the password for a server. - Retrieves the password for use with SMTP and POP3 for a single server. - Simply supply the unique identifier for the required server. + This password can be used for SMTP, POP3, and IMAP connectivity. - :param id: The identifier of the server. + :param id: The unique identifier of the server. :type id: str - :return: str + :return: The server's password. :rtype: str - :raises: - :class:`MailosaurException` """ url = "%sapi/servers/%s/password" % (self.base_url, id) response = self.session.get(url) @@ -114,19 +109,14 @@ def get_password(self, id): def update( self, id, server): - """Update a server. + """Updates the attributes of a server. - Updats a single server and returns it. - - :param id: The identifier of the server to be updated. + :param id: The unique identifier of the server. :type id: str - :param server: + :param server: The updated server. :type server: ~mailosaur.models.Server - :param dict custom_headers: headers that will be added to the request - :return: Server + :return: The updated server. :rtype: ~mailosaur.models.Server - :raises: - :class:`MailosaurException` """ url = "%sapi/servers/%s" % (self.base_url, id) response = self.session.put(url, json=server.to_json()) @@ -141,17 +131,15 @@ def update( def delete( self, id): - """Delete a server. + """Permanently delete a server. - Permanently deletes a server. This operation cannot be undone. Also - deletes all messages and associated attachments within the server. + This will also delete all messages, associated attachments, etc. within + the server. This operation cannot be undone. - :param id: The identifier of the server to be deleted. - :type id: str + :param id: The unique identifier of the server. + :type id: str :return: None :rtype: None - :raises: - :class:`MailosaurException` """ url = "%sapi/servers/%s" % (self.base_url, id) response = self.session.delete(url) diff --git a/mailosaur/operations/usage_operations.py b/mailosaur/operations/usage_operations.py index e681155..5d20ff5 100644 --- a/mailosaur/operations/usage_operations.py +++ b/mailosaur/operations/usage_operations.py @@ -3,7 +3,9 @@ from ..models import MailosaurException class UsageOperations(object): - """UsageOperations operations. + """Operations for inspecting your account's usage limits and recent transactional + usage. These endpoints require authentication with an account-level API key. + Accessed via ``client.usage``. """ def __init__(self, session, base_url, handle_http_error): @@ -14,12 +16,11 @@ def __init__(self, session, base_url, handle_http_error): def limits(self): """Retrieve account usage limits. - Details the current limits and usage for your account. + Details the current limits and usage for your account. This endpoint + requires authentication with an account-level API key. - :return: UsageAccountLimits + :return: The usage limits for your account. :rtype: ~mailosaur.models.UsageAccountLimits - :raises: - :class:`MailosaurException` """ url = "%sapi/usage/limits" % (self.base_url) response = self.session.get(url) @@ -35,12 +36,10 @@ def limits(self): def transactions(self): """Retrieves the last 31 days of transactional usage. - Details the usage transactions processed by Mailosaur in the last 31 days. + This endpoint requires authentication with an account-level API key. - :return: UsageTransactionListResult + :return: The transactional usage for the last 31 days. :rtype: ~mailosaur.models.UsageTransactionListResult - :raises: - :class:`MailosaurException` """ url = "%sapi/usage/transactions" % (self.base_url) response = self.session.get(url) From 898caddff7420a8bb7726cb52023bc8538ed9d01 Mon Sep 17 00:00:00 2001 From: Jon M Date: Wed, 27 May 2026 09:15:58 +0100 Subject: [PATCH 2/2] Use inbox (server) terminology in doc comments Normalise Intellisense prose to lead with the UI term "inbox", glossing "(server)" on entity mentions across the operations and model doc comments. Code identifiers, :param: names, and Server cross-references are unchanged. --- mailosaur/mailosaur_client.py | 2 +- mailosaur/models/message.py | 2 +- mailosaur/models/server.py | 10 ++--- mailosaur/models/server_create_options.py | 4 +- mailosaur/models/server_list_result.py | 8 ++-- mailosaur/operations/devices_operations.py | 6 +-- mailosaur/operations/messages_operations.py | 14 +++--- mailosaur/operations/servers_operations.py | 48 ++++++++++----------- 8 files changed, 47 insertions(+), 47 deletions(-) diff --git a/mailosaur/mailosaur_client.py b/mailosaur/mailosaur_client.py index 11a04f0..a294ae9 100644 --- a/mailosaur/mailosaur_client.py +++ b/mailosaur/mailosaur_client.py @@ -36,7 +36,7 @@ class MailosaurClient(object): :vartype files: ~mailosaur.operations.files_operations.FilesOperations :ivar messages: Operations for finding, retrieving, creating, and managing email and SMS messages. :vartype messages: ~mailosaur.operations.messages_operations.MessagesOperations - :ivar servers: Operations for creating and managing your Mailosaur servers (virtual inboxes). + :ivar servers: Operations for creating and managing your Mailosaur inboxes (servers). :vartype servers: ~mailosaur.operations.servers_operations.ServersOperations :ivar usage: Operations for inspecting account usage limits and recent transactional usage. :vartype usage: ~mailosaur.operations.usage_operations.UsageOperations diff --git a/mailosaur/models/message.py b/mailosaur/models/message.py index 043301c..afd262d 100644 --- a/mailosaur/models/message.py +++ b/mailosaur/models/message.py @@ -34,7 +34,7 @@ class Message(object): :type attachments: list[~mailosaur.models.Attachment] :param metadata: :type metadata: ~mailosaur.models.Metadata - :param server: Identifier for the server in which the message is located. + :param server: Identifier for the inbox (server) in which the message is located. :type server: str """ diff --git a/mailosaur/models/server.py b/mailosaur/models/server.py index 12b33a8..183fb36 100644 --- a/mailosaur/models/server.py +++ b/mailosaur/models/server.py @@ -1,15 +1,15 @@ class Server(object): - """Server. + """A Mailosaur inbox (server) - a virtual SMTP/SMS endpoint. - :param id: Unique identifier for the server. Used as username for + :param id: Unique identifier for the inbox (server). Used as username for SMTP/POP3 authentication. :type id: str - :param name: A name used to identify the server. + :param name: A name used to identify the inbox (server). :type name: str :param users: Users (excluding administrators) who have access to the - server. + inbox (server) when access is restricted. :type users: list[str] - :param messages: The number of messages currently in the server. + :param messages: The number of messages currently in the inbox (server). :type messages: int """ diff --git a/mailosaur/models/server_create_options.py b/mailosaur/models/server_create_options.py index e881586..05c84b1 100644 --- a/mailosaur/models/server_create_options.py +++ b/mailosaur/models/server_create_options.py @@ -1,7 +1,7 @@ class ServerCreateOptions(object): - """ServerCreateOptions. + """Options used to create a new Mailosaur inbox (server). - :param name: A name used to identify the server. + :param name: A name used to identify the inbox (server). :type name: str """ diff --git a/mailosaur/models/server_list_result.py b/mailosaur/models/server_list_result.py index d6de784..3f8ad70 100644 --- a/mailosaur/models/server_list_result.py +++ b/mailosaur/models/server_list_result.py @@ -1,9 +1,9 @@ class ServerListResult(object): - """The result of a server listing request. + """The result of an inbox (server) listing request. - :param items: The individual servers forming the result. Servers are - returned sorted by creation date, with the most recently-created server - appearing first. + :param items: The individual inboxes (servers) forming the result. Inboxes + (servers) are returned sorted by creation date, with the most + recently-created inbox (server) appearing first. :type items: list[~mailosaur.models.Server] """ diff --git a/mailosaur/operations/devices_operations.py b/mailosaur/operations/devices_operations.py index 6c167c8..b62e2d9 100644 --- a/mailosaur/operations/devices_operations.py +++ b/mailosaur/operations/devices_operations.py @@ -22,11 +22,11 @@ def __init__(self, session, base_url, handle_http_error): def generate_email_address(self, server): """Generates a random email address by appending a random string in front of - the server's domain name. + the domain name of the inbox (server). - :param server: The identifier of the server. + :param server: The identifier of the inbox (server). :type server: str - :return: A random email address ending in the server's domain. + :return: A random email address ending in the domain of the inbox (server). :rtype: str """ host = os.getenv('MAILOSAUR_SMTP_HOST', 'mailosaur.net') diff --git a/mailosaur/operations/messages_operations.py b/mailosaur/operations/messages_operations.py index 0e08cf6..6304d9f 100644 --- a/mailosaur/operations/messages_operations.py +++ b/mailosaur/operations/messages_operations.py @@ -8,7 +8,7 @@ class MessagesOperations(object): """Operations for finding, retrieving, creating, forwarding, replying to, and - deleting the email and SMS messages received by your Mailosaur servers. + deleting the email and SMS messages received by your Mailosaur inboxes (servers). Accessed via ``client.messages``. """ @@ -24,7 +24,7 @@ def get(self, server, criteria, timeout=10000, received_after=(datetime.today() **Recommended:** This is the most efficient method of looking up a message, therefore we recommend using it wherever possible. - :param server: The unique identifier of the containing server. + :param server: The unique identifier of the containing inbox (server). :type server: str :param criteria: The criteria with which to find messages during a search. :type criteria: ~mailosaur.models.SearchCriteria @@ -96,7 +96,7 @@ def list(self, server, page=None, items_per_page=None, received_after=None, dir= The summaries are returned sorted by received date, with the most recently-received messages appearing first. - :param server: The unique identifier of the required server. + :param server: The unique identifier of the required inbox (server). :type server: str :param page: Used in conjunction with `itemsPerPage` to support pagination. @@ -130,11 +130,11 @@ def list(self, server, page=None, items_per_page=None, received_after=None, dir= return MessageListResult(data) def delete_all(self, server): - """Permanently delete all messages within a server. + """Permanently delete all messages within an inbox (server). This operation cannot be undone. - :param server: The unique identifier of the server. + :param server: The unique identifier of the inbox (server). :type server: str :return: None :rtype: None @@ -153,7 +153,7 @@ def search(self, server, criteria, page=None, items_per_page=None, timeout=None, The messages are returned sorted by received date, with the most recently-received messages appearing first. - :param server: The unique identifier of the server to search. + :param server: The unique identifier of the inbox (server) to search. :type server: str :param criteria: The criteria with which to find messages during a search. :type criteria: ~mailosaur.models.SearchCriteria @@ -231,7 +231,7 @@ def create(self, server, options): This is useful in scenarios where you want an email to trigger a workflow in your product. - :param server: The unique identifier of the required server. + :param server: The unique identifier of the required inbox (server). :type server: str :param options: Options to use when creating a new message. :type options: ~mailosaur.models.MessageCreateOptions diff --git a/mailosaur/operations/servers_operations.py b/mailosaur/operations/servers_operations.py index 9fc331d..0446ed3 100644 --- a/mailosaur/operations/servers_operations.py +++ b/mailosaur/operations/servers_operations.py @@ -6,8 +6,8 @@ from ..models import MailosaurException class ServersOperations(object): - """Operations for creating and managing your Mailosaur servers - the virtual - inboxes that group your tests together, each with its own domain and + """Operations for creating and managing your Mailosaur inboxes (servers) - they + group your tests together, each with its own domain and SMTP/POP3/IMAP credentials. Accessed via ``client.servers``. """ @@ -18,11 +18,11 @@ def __init__(self, session, base_url, handle_http_error): def generate_email_address(self, server): """Generates a random email address by appending a random string in front of - the server's domain name. + the domain name of the inbox (server). - :param server: The identifier of the server. + :param server: The identifier of the inbox (server). :type server: str - :return: A random email address ending in the server's domain. + :return: A random email address ending in the domain of the inbox (server). :rtype: str """ host = os.getenv('MAILOSAUR_SMTP_HOST', 'mailosaur.net') @@ -30,11 +30,11 @@ def generate_email_address(self, server): return "%s@%s.%s" % (randomString, server, host) def list(self): - """Returns a list of your virtual servers. + """Returns a list of your inboxes (servers). - Servers are returned sorted in alphabetical order. + Inboxes (servers) are returned sorted in alphabetical order. - :return: A result containing your servers. + :return: A result containing your inboxes (servers). :rtype: ~mailosaur.models.ServerListResult """ url = "%sapi/servers" % (self.base_url) @@ -49,11 +49,11 @@ def list(self): return ServerListResult(data) def create(self, server_create_options): - """Creates a new virtual server. + """Creates a new inbox (server). - :param server_create_options: Options used to create a new Mailosaur server. + :param server_create_options: Options used to create a new Mailosaur inbox (server). :type server_create_options: ~mailosaur.models.ServerCreateOptions - :return: The newly-created server. + :return: The newly-created inbox (server). :rtype: ~mailosaur.models.Server """ url = "%sapi/servers" % (self.base_url) @@ -68,11 +68,11 @@ def create(self, server_create_options): return Server(data) def get(self, id): - """Retrieves the detail for a single server. + """Retrieves the detail for a single inbox (server). - :param id: The unique identifier of the server. + :param id: The unique identifier of the inbox (server). :type id: str - :return: The server. + :return: The inbox (server). :rtype: ~mailosaur.models.Server """ url = "%sapi/servers/%s" % (self.base_url, id) @@ -87,13 +87,13 @@ def get(self, id): return Server(data) def get_password(self, id): - """Retrieves the password for a server. + """Retrieves the password for an inbox (server). This password can be used for SMTP, POP3, and IMAP connectivity. - :param id: The unique identifier of the server. + :param id: The unique identifier of the inbox (server). :type id: str - :return: The server's password. + :return: The password for the inbox (server). :rtype: str """ url = "%sapi/servers/%s/password" % (self.base_url, id) @@ -109,13 +109,13 @@ def get_password(self, id): def update( self, id, server): - """Updates the attributes of a server. + """Updates the attributes of an inbox (server). - :param id: The unique identifier of the server. + :param id: The unique identifier of the inbox (server). :type id: str - :param server: The updated server. + :param server: The updated inbox (server). :type server: ~mailosaur.models.Server - :return: The updated server. + :return: The updated inbox (server). :rtype: ~mailosaur.models.Server """ url = "%sapi/servers/%s" % (self.base_url, id) @@ -131,12 +131,12 @@ def update( def delete( self, id): - """Permanently delete a server. + """Permanently delete an inbox (server). This will also delete all messages, associated attachments, etc. within - the server. This operation cannot be undone. + the inbox (server). This operation cannot be undone. - :param id: The unique identifier of the server. + :param id: The unique identifier of the inbox (server). :type id: str :return: None :rtype: None