Merge pull request #6 from socketlabs/feature/metadata-tags

Feature/metadata tags

Author: david-schrenker

README.md

@@ -1,4 +1,4 @@
-[![SocketLabs](https://static.socketlabs.com/logos/logo-dark-326x64.png)](https://www.socketlabs.com/developers) 
+[![SocketLabs](https://static.socketlabs.com/logos/logo-dark-326x64.png)](https://www.socketlabs.com/developers)
 # [![Twitter Follow](https://img.shields.io/twitter/follow/socketlabs.svg?style=social&label=Follow)](https://twitter.com/socketlabs) [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/socketlabs/socketlabs-csharp/blob/master/CONTRIBUTING.md)
 <!--
 [![GitHub contributors](https://img.shields.io/github/contributors/socketlabs/socketlabs-python.svg)](https://github.com/socketlabs/socketlabs-python/graphs/contributors)
@@ -28,12 +28,12 @@ pip install socketlabs-injectionapi
 ```
 ### From a local archive using pip
 
-You can just download the package and install from a local archive file. 
+You can just download the package and install from a local archive file.
 
-> [socketlabs_injectionapi-1.2.1.tar.gz](https://github.com/socketlabs/socketlabs-python/releases/download/1.2python setup.py sdist bdist_wheel.1/socketlabs_injectionapi-1.2.1.tar.gz)
+> [socketlabs_injectionapi-1.4.0.tar.gz](https://github.com/socketlabs/socketlabs-python/releases/download/1.4.0/socketlabs_injectionapi-1.4.0.tar.gz)
 
 ```
-pip install <path>/socketlabs_injectionapi-1.2.1.tar.gz
+pip install <path>/socketlabs_injectionapi-1.4.0.tar.gz
 ```
 
 ### From git using pip
@@ -45,21 +45,21 @@ For more information please see the [Installing Packages](https://packaging.pyth
 <a name="getting-started" id="getting-started"></a>
 # Getting Started
 ## Obtaining your API Key and SocketLabs ServerId number
-In order to get started, you'll need to enable the Injection API feature in the [SocketLabs Control Panel](https://cp.socketlabs.com). 
-Once logged in, navigate to your SocketLabs server's dashboard (if you only have one server on your account you'll be taken here immediately after logging in). 
-Make note of your 4 or 5 digit ServerId number, as you'll need this along with 
-your API key in order to use the Injection API. 
+In order to get started, you'll need to enable the Injection API feature in the [SocketLabs Control Panel](https://cp.socketlabs.com).
+Once logged in, navigate to your SocketLabs server's dashboard (if you only have one server on your account you'll be taken here immediately after logging in).
+Make note of your 4 or 5 digit ServerId number, as you'll need this along with
+your API key in order to use the Injection API.
 
-To enable the Injection API, click on the "For Developers" dropdown on the top-level navigation, then choose the "Configure HTTP Injection API" option. 
+To enable the Injection API, click on the "For Developers" dropdown on the top-level navigation, then choose the "Configure HTTP Injection API" option.
 Once here, you can enable the feature by choosing the "Enabled" option in the
-dropdown. Enabling the feature will also generate your API key, which you'll 
-need (along with your ServerId) to start using the API. Be sure to click the 
+dropdown. Enabling the feature will also generate your API key, which you'll
+need (along with your ServerId) to start using the API. Be sure to click the
 "Update" button to save your changes once you are finished.
 
 
 ## Basic Message
-A basic message is an email message like you'd send from a personal email client such as Outlook. 
-A basic message can have many recipients, including multiple To addresses, CC addresses, and even BCC addresses. 
+A basic message is an email message like you'd send from a personal email client such as Outlook.
+A basic message can have many recipients, including multiple To addresses, CC addresses, and even BCC addresses.
 You can also send a file attachment in a basic message.
 
 ```python
@@ -78,7 +78,7 @@ message.plain_text_body = "This is the Plain Text Body of my message.";
 
 message.from_email_address = EmailAddress("[email protected]")
 
-# A basic message supports up to 50 recipients 
+# A basic message supports up to 50 recipients
 # and supports several different ways to add recipients
 
 # Add a To address by passing the email address
@@ -98,9 +98,9 @@ response = client.send(message)
 ```
 
 ## Bulk Message
-A bulk message usually contains a single recipient per message 
-and is generally used to send the same content to many recipients, 
-optionally customizing the message via the use of MergeData. 
+A bulk message usually contains a single recipient per message
+and is generally used to send the same content to many recipients,
+optionally customizing the message via the use of MergeData.
 For more information about using Merge data, please see the [Injection API documentation](https://www.socketlabs.com/docs/inject/).
 ```python
 from socketlabs.injectionapi import SocketLabsClient
@@ -131,28 +131,28 @@ response = client.send(message)
 
 <a name="managing-api-keys" id="managing-api-keys"></a>
 ## Managing API Keys
-For ease of demonstration, many of our examples include the ServerId (SOCKETLABS_SERVER_ID) and API key 
-(SOCKETLABS_INJECTION_API_KEY) directly in our code sample. Generally it is not considered a good practice to store 
-sensitive information like this directly in your code. Depending on your project type, we recommend either storing your 
-credentials using Environment Variables. For more information please see: 
+For ease of demonstration, many of our examples include the ServerId (SOCKETLABS_SERVER_ID) and API key
+(SOCKETLABS_INJECTION_API_KEY) directly in our code sample. Generally it is not considered a good practice to store
+sensitive information like this directly in your code. Depending on your project type, we recommend either storing your
+credentials using Environment Variables. For more information please see:
 [Using Environment Variables](https://docs.microsoft.com/en-us/dotnet/api/system.environment.getenvironmentvariable)
 
 
 <a name="examples-and-use-cases" id="examples-and-use-cases"></a>
 # Examples and Use Cases
-In order to demonstrate the many possible use cases for the SDK, we've provided 
-an assortment of code examples. These examples demonstrate many different 
-features available to the Injection API and SDK, including using templates 
-created in the [SocketLabs Email Designer](https://www.socketlabs.com/blog/introducing-new-email-designer/), custom email headers, sending 
-attachments, sending content that is stored in an HTML file, advanced bulk 
+In order to demonstrate the many possible use cases for the SDK, we've provided
+an assortment of code examples. These examples demonstrate many different
+features available to the Injection API and SDK, including using templates
+created in the [SocketLabs Email Designer](https://www.socketlabs.com/blog/introducing-new-email-designer/), custom email headers, sending
+attachments, sending content that is stored in an HTML file, advanced bulk
 merging, and even pulling recipients from a datasource.
 
 ### [Basic send from SocketLabs Template](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/basic/basic_send_with_api_template.py)
-This example demonstrates the sending of a piece of content that was created in the 
+This example demonstrates the sending of a piece of content that was created in the
 SocketLabs Email Designer. This is also known as the [API Templates](https://www.socketlabs.com/blog/introducing-api-templates/) feature.
 
 ### [Basic send from HTML file](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/basic/basic_send_from_html_file.py)
-This example demonstrates how to read in your HTML content from an HTML file 
+This example demonstrates how to read in your HTML content from an HTML file
 rather than passing in a string directly.
 
 ### [Basic send with file attachment](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/basic/basic_send_with_attachment.py)
@@ -196,19 +196,19 @@ This example demonstrates the results of attempting to do a send with invalid re
 This example demonstrates how to send a bulk message to multiple recipients.
 
 ### [Bulk send with merge data](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/bulk/bulk_send_from_data_source_with_merge.py)
-This example demonstrates how to send a bulk message to multiple recipients with 
+This example demonstrates how to send a bulk message to multiple recipients with
 unique merge data per recipient.
 
 ### [Bulk send with complex merge including attachments](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/bulk/bulk_send_complex.py)
-This example demonstrates many features of the `BulkMessage()`, including 
+This example demonstrates many features of the `BulkMessage()`, including
 adding multiple recipients, merge data, and adding an attachment.
 
 ### [Bulk send with recipients pulled from a datasource](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/bulk/bulk_send_with_ascii_charset_merge_data.py)
-This example uses a mock repository class to demonstrate how you would pull 
+This example uses a mock repository class to demonstrate how you would pull
 your recipients from a database and create a bulk mailing with merge data.
 
 ### [Bulk send with Ascii charset and special characters](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/bulk/bulk_send_with_ascii_charset_merge_data.py)
-This example demonstrates how to send a bulk message with a specified character 
+This example demonstrates how to send a bulk message with a specified character
 set and special characters.
 
 ### [Bulk send with Amp ](https://github.com/socketlabs/socketlabs-python/blob/main/python-examples/bulk/bulk_send_with_amp_body.py)
@@ -217,6 +217,7 @@ For more information about AMP please see [AMP Project](https://amp.dev/document
 
 <a name="version"></a>
 # Version
+* 1.4.0 - Adding Metadata and Tags
 * 1.2.1 - Adding optional retry logic for Http requests. If configured, the request will retry when certain 500 errors occur (500, 502, 503, 504)
 * 1.1.1 - Adding request timeout value on the client for Http requests
 * 1.1.0 - Adds Amp Html Support

python-examples/basic/basic_send_complex.py

@@ -3,7 +3,7 @@
 
 from socketlabs.injectionapi import SocketLabsClient
 from socketlabs.injectionapi.message.__imports__ import \
-    Attachment, BasicMessage, CustomHeader, EmailAddress
+    Attachment, BasicMessage, CustomHeader, EmailAddress, Metadata
 
 
 # build the message
@@ -132,6 +132,37 @@
 # Add CustomHeader using the add_custom_header function
 message.add_custom_header("testMessageHeader", "I am a message header")
 
+# Adding Metadata
+# ==========================
+# Add Metadata using a list
+
+metadata = [
+    Metadata("example-type", "basic-send-complex-example"),
+    Metadata("message-contains", "attachments, headers")
+]
+message.metadata = metadata
+
+# Add Metadata directly to the list
+message.metadata.append(Metadata("message-has-attachments", "true"))
+
+# Add Metadata using the add_metadata function
+message.add_metadata("testMessageHeader", "I am metadata")
+
+# Adding Tags
+# ==========================
+# Add Metadata using a list
+
+tags = [
+    "example-type:basic-send-complex-example"
+]
+message.tags = tags
+
+# Add Metadata directly to the list
+message.tags.append("message-has-attachments:true")
+
+# Add Metadata using the add_metadata function
+message.add_tag("I am a test message")
+message.add_tag("python-Example")
 
 # get credentials from environment variables
 server_id = int(os.environ.get('SOCKETLABS_SERVER_ID'))

python-examples/bulk/bulk_send_complex.py

@@ -3,7 +3,7 @@
 
 from socketlabs.injectionapi import SocketLabsClient
 from socketlabs.injectionapi.message.__imports__ import \
-    Attachment, BulkMessage, BulkRecipient, CustomHeader, EmailAddress
+    Attachment, BulkMessage, BulkRecipient, CustomHeader, EmailAddress, Metadata
 
 
 # build the message
@@ -156,7 +156,6 @@
 
 message.add_attachment(attachment4)
 
-
 # Adding Custom Headers
 # ==========================
 # Add CustomHeader using a list
@@ -172,6 +171,37 @@
 # Add CustomHeader using the add_custom_header function
 message.add_custom_header("testMessageHeader", "I am a message header")
 
+# Adding Metadata
+# ==========================
+# Add Metadata using a list
+
+metadata = [
+    Metadata("example-type", "basic-send-complex-example"),
+    Metadata("message-contains", "attachments, headers")
+]
+message.metadata = metadata
+
+# Add Metadata directly to the list
+message.metadata.append(Metadata("message-has-attachments", "true"))
+
+# Add Metadata using the add_metadata function
+message.add_metadata("testMessageHeader", "I am metadata")
+
+# Adding Tags
+# ==========================
+# Add Metadata using a list
+
+tags = [
+    "example-type:basic-send-complex-example"
+]
+message.tags = tags
+
+# Add Metadata directly to the list
+message.tags.append("message-has-attachments:true")
+
+# Add Metadata using the add_metadata function
+message.add_tag("I am a test message")
+message.add_tag("python-Example")
 
 # get credentials from environment variables
 server_id = int(os.environ.get('SOCKETLABS_SERVER_ID'))

setup.py

@@ -23,6 +23,7 @@
         'Programming Language :: Python :: 3.6',
         'Programming Language :: Python :: 3.7',
         'Programming Language :: Python :: 3.8',
+        'Programming Language :: Python :: 3.9',
         "License :: OSI Approved :: MIT License",
         "Operating System :: OS Independent",
     ],

socketlabs/injectionapi/core/injectionrequestfactory.py

@@ -5,6 +5,7 @@
 from ..core.serialization.mergedatajson import MergeDataJson
 from ..core.serialization.mergefieldjson import MergeFieldJson
 from ..core.serialization.messagejson import MessageJson
+from ..core.serialization.metadatajson import MetadataJson
 from ..message.basicmessage import BasicMessage
 from ..message.bulkmessage import BulkMessage
 from ..message.bulkrecipient import BulkRecipient
@@ -56,6 +57,22 @@ def populate_custom_headers(custom_headers: list):
     return custom_header_json
 
 
+def populate_metadata(metadata: list):
+    """
+    Converts a List of Metadata objects to a List of MetadataJson objects.
+    :param metadata: list of Metadata to convert
+    :type metadata: list
+    :return the converted list of MetadataJson
+    :rtype list
+    """
+    if metadata is None:
+        return None
+    metadata_json = []
+    for item in metadata:
+        metadata_json.append(MetadataJson(item.name, item.value))
+    return metadata_json
+
+
 def populate_attachments(attachments: list):
     """
     Converts a list of Attachment objects to a List of AttachmentJson objects.
@@ -149,6 +166,9 @@ def generate_base_message(message: MessageBase):
     message_json.from_email_address = email_address_to_address_json(message.from_email_address)
     message_json.custom_headers = populate_custom_headers(message.custom_headers)
     message_json.attachments = populate_attachments(message.attachments)
+    message_json.metadata = populate_metadata(message.custom_headers)
+    message_json.tags = message.tags
+
     if message.api_template is not None:
         message_json.api_template = str(message.api_template)
 

socketlabs/injectionapi/core/sendvalidator.py

@@ -39,6 +39,10 @@ def validate_base_message(message: MessageBase):
         if not has_valid_custom_headers(message.custom_headers):
             return SendResult.MessageValidationInvalidCustomHeaders
 
+    if message.metadata is not None and len(message.metadata) > 0:
+        if not has_valid_metadata(message.metadata):
+            return SendResult.MessageValidationInvalidMetadata
+
     return SendResult.Success
 
 
@@ -294,6 +298,23 @@ def has_valid_custom_headers(custom_headers: list):
     return True
 
 
+def has_valid_metadata(metadata: list):
+    """
+    Check if the list of metadata is valid
+    :param metadata: list of Metadata to validate
+    :type metadata: list
+    :return the result
+     :rtype bool
+    """
+    if metadata is None:
+        return True
+    for item in metadata:
+        valid = item.isvalid()
+        if valid is False:
+            return False
+    return True
+
+
 def validate_basic_message(message: BasicMessage):
     """
     Validate a basic email message before sending to the Injection API.