Skip to content

Commit 1d48ab4

Browse files
david-schrenkerdavid-schrenker
committed
Initial commit
1 parent 35ec40c commit 1d48ab4

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

65 files changed

+6504
-1
lines changed

Diff for: ‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ __pycache__/
55

66
# C extensions
77
*.so
8+
*.sou
89

910
# Distribution / packaging
1011
.Python
@@ -102,3 +103,5 @@ venv.bak/
102103

103104
# mypy
104105
.mypy_cache/
106+
107+
.idea/

Diff for: ‎CONTRIBUTING.md

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Contributing to 'socketlabs-python'
2+
3+
If you discover issues, have ideas for improvements or new features,
4+
please report them to the [issue tracker](https://github.com/socketlabs/socketlabs-python/issues) of the repository or
5+
submit a pull request. Please, try to follow these guidelines when you
6+
do so.
7+
8+
- [Issue Reporting](#reporting)
9+
- [Feature Requests](#feature)
10+
- [Pull Requests](#pull)
11+
12+
13+
## <a name="reporting"></a>Issue reporting
14+
15+
* Check that the issue has not already been reported.
16+
* Check that the issue has not already been fixed in the latest code
17+
(a.k.a. `master`).
18+
* Be clear, concise and precise in your description of the problem.
19+
* Open an issue with a descriptive title and a summary in grammatically correct,
20+
complete sentences.
21+
* Mention the version info.
22+
23+
## <a name="feature"></a> Want a Feature?
24+
25+
You can request a new feature by submitting an issue to our
26+
[GitHub Repository](https://github.com/socketlabs/socketlabs-python). If you would like to implement a new feature then
27+
consider what kind of change it is:
28+
29+
* **Major Changes** that you wish to contribute to the project should be
30+
discussed first with `csharp-socketlabs` contributors in an issue or pull request so
31+
that we can develop a proper solution and better coordinate our efforts,
32+
prevent duplication of work, and help you to craft the change so that it is
33+
successfully accepted into the project.
34+
* **Small Changes** can be crafted and submitted to the
35+
[GitHub Repository](https://github.com/socketlabs/socketlabs-python) as a Pull Request.
36+
37+
## <a name="pull"></a> Creating a Pull Request?
38+
39+
- Create a personal fork of the project on Github.
40+
- If you created your fork a while ago be sure to pull upstream changes into your local repository.
41+
- Create a new branch to work on! Branch from `master`.
42+
- Implement/fix your feature, comment your code.
43+
- Write or adapt tests as needed.
44+
- Add or change the documentation as needed.
45+
- Squash your commits into a single commit with git's [interactive rebase](https://help.github.com/articles/interactive-rebase). Create a new branch if necessary.
46+
- Push your branch to your fork on Github, the remote `origin`.
47+
- From your fork open a pull request with a clear title and description in grammatically correct, complete sentences.

Diff for: ‎LICENSE renamed to ‎LICENSE.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
1818
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
1919
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
2020
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21-
SOFTWARE.
21+
SOFTWARE.

Diff for: ‎MANIFEST.in

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
include README.md
2+
include LICENSE.md
3+
include CONTRIBUTING.md
4+
include app.json
5+
recursive-exclude tests *

Diff for: ‎README.md

+213
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
[![SocketLabs](https://www.socketlabs.com/assets/socketlabs-logo1.png)](https://www.socketlabs.com)
2+
# [![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)
3+
<!--
4+
[![GitHub contributors](https://img.shields.io/github/contributors/socketlabs/socketlabs-python.svg)](https://github.com/socketlabs/socketlabs-python/graphs/contributors)
5+
-->
6+
7+
The SocketLabs Email Delivery Python library allows you to easily send email messages via the [SocketLabs Injection API](https://www.socketlabs.com/api-reference/injection-api/). The library makes it easy to build and send any type of message supported by the API, from a simple message to a single recipient all the way to a complex bulk message sent to a group of recipients with unique merge data per recipient.
8+
9+
# Table of Contents
10+
* [Prerequisites and Installation](#prerequisites-and-installation)
11+
* [Getting Started](#getting-started)
12+
* [Managing API Keys](#managing-api-keys)
13+
* [Examples and Use Cases](#examples-and-use-cases)
14+
* [License](#license)
15+
16+
17+
<a name="prerequisites-and-installation" id="prerequisites-and-installation"></a>
18+
# Prerequisites and Installation
19+
## Prerequisites
20+
* A supported Python version (3.4, 3.5, 3.6, 3.7)
21+
* A SocketLabs account. If you don't have one yet, you can [sign up for a free account](https://signup.socketlabs.com/step-1?plan=free) to get started.
22+
23+
## Installation
24+
25+
### pip
26+
```
27+
pip install socketlabs-injectionapi
28+
```
29+
### From a local archive using pip
30+
31+
You can just download the package and install from a local archive file.
32+
33+
> [socketlabs_injectionapi-1.0.0.tar.gz](https://github.com/socketlabs/socketlabs-python/releases/download/1.0.0/socketlabs_injectionapi-1.0.0.tar.gz)
34+
35+
```
36+
pip install <path>/socketlabs_injectionapi-1.0.0.tar.gz
37+
```
38+
39+
### From git using pip
40+
```
41+
pip install git+https://github.com/socketlabs/socketlabs-python.git#egg=socketlabs_injectionapi
42+
```
43+
For more information please see the [Installing Packages](https://packaging.python.org/tutorials/installing-packages/) tutorial
44+
45+
<a name="getting-started" id="getting-started"></a>
46+
# Getting Started
47+
## Obtaining your API Key and SocketLabs ServerId number
48+
In order to get started, you'll need to enable the Injection API feature in the [SocketLabs Control Panel](https://cp.socketlabs.com).
49+
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).
50+
Make note of your 4 or 5 digit ServerId number, as you'll need this along with
51+
your API key in order to use the Injection API.
52+
53+
To enable the Injection API, click on the "For Developers" dropdown on the top-level navigation, then choose the "Configure HTTP Injection API" option.
54+
Once here, you can enable the feature by choosing the "Enabled" option in the
55+
dropdown. Enabling the feature will also generate your API key, which you'll
56+
need (along with your ServerId) to start using the API. Be sure to click the
57+
"Update" button to save your changes once you are finished.
58+
59+
60+
## Basic Message
61+
A basic message is an email message like you'd send from a personal email client such as Outlook.
62+
A basic message can have many recipients, including multiple To addresses, CC addresses, and even BCC addresses.
63+
You can also send a file attachment in a basic message.
64+
65+
```python
66+
from socketlabs.injectionapi import SocketLabsClient
67+
from socketlabs.injectionapi.message.basicmessage import BasicMessage
68+
from socketlabs.injectionapi.message.emailaddress import EmailAddress
69+
70+
# Your SocketLabs ServerId and Injection API key
71+
client = SocketLabsClient(10000, "YOUR-API-KEY");
72+
73+
message = BasicMessage()
74+
75+
message.subject = "Sending A BasicMessage"
76+
message.html_body = "<html>This is the Html Body of my message.</html>"
77+
message.plain_text_body = "This is the Plain Text Body of my message.";
78+
79+
message.from_email_address = EmailAddress("[email protected]")
80+
81+
# A basic message supports up to 50 recipients
82+
# and supports several different ways to add recipients
83+
84+
# Add a To address by passing the email address
85+
message.to_email_address.append(EmailAddress("[email protected]"))
86+
message.to_email_address.append(EmailAddress("[email protected]", "Recipient #2"))
87+
88+
# // Adding CC Recipients
89+
message.add_cc_email_address("[email protected]")
90+
message.add_cc_email_address("[email protected]", "Recipient #4")
91+
92+
# Adding Bcc Recipients
93+
message.add_bcc_email_address(EmailAddress("[email protected]"))
94+
message.add_bcc_email_address(EmailAddress("[email protected]", "Recipient #6"))
95+
96+
97+
response = client.send(message)
98+
```
99+
100+
## Bulk Message
101+
A bulk message usually contains a single recipient per message
102+
and is generally used to send the same content to many recipients,
103+
optionally customizing the message via the use of MergeData.
104+
For more information about using Merge data, please see the [Injection API documentation](https://www.socketlabs.com/api-reference/injection-api/#merging).
105+
```python
106+
from socketlabs.injectionapi import SocketLabsClient
107+
from socketlabs.injectionapi.message.bulkmessage import BulkMessage
108+
from socketlabs.injectionapi.message.bulkrecipient import BulkRecipient
109+
from socketlabs.injectionapi.message.emailaddress import EmailAddress
110+
111+
# Your SocketLabs ServerId and Injection API key
112+
client = SocketLabsClient(10000, "YOUR-API-KEY");
113+
114+
message = BulkMessage()
115+
116+
message.plain_text_body = "This is the body of my message sent to %%Name%%"
117+
message.html_body = "<html>This is the HtmlBody of my message sent to %%Name%%</html>"
118+
message.subject = tests
119+
message.from_email_address = EmailAddress("[email protected]")
120+
121+
recipient1 = BulkRecipient("[email protected]")
122+
recipient1.add_merge_data("Name", "Recipient1")
123+
message.add_to_recipient(recipient1)
124+
125+
recipient2 = BulkRecipient("[email protected]", "Recipient #2")
126+
recipient2.add_merge_data("Name", "Recipient2")
127+
message.add_to_recipient(recipient2)
128+
129+
response = client.send(message)
130+
```
131+
132+
<a name="managing-api-keys" id="managing-api-keys"></a>
133+
## Managing API Keys
134+
For ease of demonstration, many of our examples include the ServerId (SOCKETLABS_SERVER_ID) and API key
135+
(SOCKETLABS_INJECTION_API_KEY) directly in our code sample. Generally it is not considered a good practice to store
136+
sensitive information like this directly in your code. Depending on your project type, we recommend either storing your
137+
credentials using Environment Variables. For more information please see:
138+
[Using Environment Variables](https://docs.microsoft.com/en-us/dotnet/api/system.environment.getenvironmentvariable)
139+
140+
141+
<a name="examples-and-use-cases" id="examples-and-use-cases"></a>
142+
# Examples and Use Cases
143+
In order to demonstrate the many possible use cases for the SDK, we've provided
144+
an assortment of code examples. These examples demonstrate many different
145+
features available to the Injection API and SDK, including using templates
146+
created in the [SocketLabs Email Designer](https://www.socketlabs.com/blog/introducing-new-email-designer/), custom email headers, sending
147+
attachments, sending content that is stored in an HTML file, advanced bulk
148+
merging, and even pulling recipients from a datasource.
149+
150+
### [Basic send example](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/basic/basic_send.py)
151+
This example demonstrates a Basic Send.
152+
153+
### [Basic send async example](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/basic/basic_async.py)
154+
Basic send async example
155+
156+
### [Basic send complex example](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/basic/basic_send_complex.py)
157+
This example demonstrates many features of the Basic Send, including adding multiple recipients, adding message and mailing id's, and adding an embedded image.
158+
159+
### [Basic send from HTML file](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/basic/basic_send_from_html_file.py)
160+
This example demonstrates how to read in your HTML content from an HTML file
161+
rather than passing in a string directly.
162+
163+
### [Basic send from SocketLabs Template](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/basic/basic_send_with_api_template.py)
164+
This example demonstrates the sending of a piece of content that was created in the
165+
SocketLabs Email Designer. This is also known as the [API Templates](https://www.socketlabs.com/blog/introducing-api-templates/) feature.
166+
167+
### [Basic send with specified character set](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/basic/basic_send_with_ascii_charset.py)
168+
This example demonstrates sending with a specific character set.
169+
170+
### [Basic send with file attachment](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/basic/basic_send_with_attachment.py)
171+
This example demonstrates how to add a file attachment to your message.
172+
173+
### [Basic send with custom email headers](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/basic/basic_send_with_custom_headers.py)
174+
This example demonstrates how to add custom headers to your email message.
175+
176+
### [Basic send with embedded image](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/basic/basic_send_with_embedded_image.py)
177+
This example demonstrates how to embed an image in your message.
178+
179+
### [Basic send with a web proxy](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/basic/basic_send_with_proxy.py)
180+
This example demonstrates how to use a proxy with your HTTP client.
181+
182+
### [Basic send with invalid file attachment](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/basic/invalid/basic_send_with_invalid_attachment.py)
183+
This example demonstrates the results of attempting to do a send with an invalid attachment.
184+
185+
### [Basic send with invalid from address](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/basic/invalid/basic_send_with_invalid_from.py)
186+
This example demonstrates the results of attempting to do a send with an invalid from address.
187+
188+
### [Basic send with invalid recipients](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/basic/invalid/basic_send_with_invalid_recipients.py)
189+
This example demonstrates the results of attempting to do a send with invalid recipients.
190+
191+
### [Bulk send with multiple recipients](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/bulk/bulk_send.py)
192+
This example demonstrates how to send a bulk message to multiple recipients.
193+
194+
### [Bulk send with merge data](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/bulk/bulk_send_from_data_source_with_merge.py)
195+
This example demonstrates how to send a bulk message to multiple recipients with
196+
unique merge data per recipient.
197+
198+
### [Bulk send with complex merge including attachments](https://github.com/socketlabs/socketlabs-python/blob/master/python-examples/bulk/bulk_send_complex.py)
199+
This example demonstrates many features of the `BulkMessage()`, including
200+
adding multiple recipients, merge data, and adding an attachment.
201+
202+
### [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)
203+
This example uses a mock repository class to demonstrate how you would pull
204+
your recipients from a database and create a bulk mailing with merge data.
205+
206+
### [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)
207+
This example demonstrates how to send a bulk message with a specified character
208+
set and special characters.
209+
210+
211+
<a name="license" id="license"></a>
212+
# License
213+
The SocketLabs.EmailDelivery library and all associated code, including any code samples, are [MIT Licensed](https://github.com/socketlabs/socketlabs-python/blob/master/LICENSE.MD).

Diff for: ‎app.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"name": "SocketLabs Injection Api",
3+
"description": "SocketLabs Email Delivery Python client library",
4+
"keywords": [
5+
"socketlabs",
6+
"deliverability",
7+
"email"
8+
],
9+
"website": "http://www.socketlabs.com",
10+
"repository": "https://github.com/socketlabs/socketlabs-python",
11+
"logo": "https://www.socketlabs.com/assets/socketlabs-logo1.png"
12+
}

Diff for: ‎python-examples/basic/basic_async.py

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
import json
2+
import os
3+
4+
from socketlabs.injectionapi import SocketLabsClient
5+
from socketlabs.injectionapi.message.__imports__ import \
6+
BasicMessage, EmailAddress
7+
8+
9+
def on_success(response):
10+
"""
11+
Handle the success response from the client
12+
:param response: the SendResponse
13+
:return: SendResponse
14+
"""
15+
print(json.dumps(response.to_json(), indent=2))
16+
17+
18+
def on_error(exception):
19+
"""
20+
Handle the error response from the client
21+
:param exception: the Exception
22+
:return: Exception
23+
"""
24+
print(json.dumps(exception.to_json(), indent=2))
25+
26+
27+
# build the message
28+
message = BasicMessage()
29+
30+
message.subject = "Sending A Test Message (Basic Send Async)"
31+
message.html_body = "<html><body>" \
32+
"<h1>Sending A Test Message</h1>" \
33+
"<p>This is the Html Body of my message.</p>" \
34+
"</body></html>"
35+
message.plain_text_body = "This is the Plain Text Body of my message."
36+
37+
message.from_email_address = EmailAddress("[email protected]")
38+
message.add_to_email_address("[email protected]")
39+
40+
41+
# get credentials from environment variables
42+
server_id = int(os.environ.get('SOCKETLABS_SERVER_ID'))
43+
api_key = os.environ.get('SOCKETLABS_INJECTION_API_KEY')
44+
45+
# create the client
46+
client = SocketLabsClient(server_id, api_key)
47+
48+
# send the message
49+
client.send_async(message, on_success, on_error)

Diff for: ‎python-examples/basic/basic_send.py

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
import json
2+
import os
3+
4+
from socketlabs.injectionapi import SocketLabsClient
5+
from socketlabs.injectionapi.message.__imports__ import \
6+
BasicMessage, EmailAddress
7+
8+
9+
# build the message
10+
message = BasicMessage()
11+
12+
message.subject = "Sending A Test Message (Basic Send)"
13+
message.html_body = "<html><body>" \
14+
"<h1>Sending A Test Message</h1>" \
15+
"<p>This is the Html Body of my message.</p>" \
16+
"</body></html>"
17+
message.plain_text_body = "This is the Plain Text Body of my message."
18+
19+
message.from_email_address = EmailAddress("[email protected]")
20+
message.add_to_email_address("[email protected]")
21+
message.add_to_email_address("[email protected]", "Recipient #2")
22+
message.add_to_email_address(EmailAddress("[email protected]"))
23+
message.add_to_email_address(EmailAddress("[email protected]", "Recipient #4"))
24+
25+
26+
# get credentials from environment variables
27+
server_id = int(os.environ.get('SOCKETLABS_SERVER_ID'))
28+
api_key = os.environ.get('SOCKETLABS_INJECTION_API_KEY')
29+
30+
# create the client
31+
client = SocketLabsClient(server_id, api_key)
32+
33+
# send the message
34+
response = client.send(message)
35+
36+
print(json.dumps(response.to_json(), indent=2))

0 commit comments

Comments
 (0)