Skip to content

Commit 0c1d37f

Browse files
BillVolzJoeSocketLabs
BillVolz
authored and
JoeSocketLabs
committed
Initial commit
0 parents  commit 0c1d37f

Some content is hidden

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

47 files changed

+2690
-0
lines changed

‎.gitignore

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Binaries for programs and plugins
2+
*.exe
3+
*.exe~
4+
*.dll
5+
*.so
6+
*.dylib
7+
debug
8+
.vscode/
9+
10+
# Test binary, build with `go test -c`
11+
*.test
12+
13+
# Output of the go coverage tool, specifically when used with LiteIDE
14+
*.out

‎CONTRIBUTING.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Contributing to 'socketlabs-go'
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-go/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-go). 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 `socketlabs-go` 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-go) 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.

‎LICENSE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2018 SocketLabs
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
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-go/blob/master/CONTRIBUTING.md)
3+
4+
The SocketLabs Email Delivery Go package 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.
5+
6+
# Table of Contents
7+
* [Prerequisites and Installation](#prerequisites-and-installation)
8+
* [Getting Started](#getting-started)
9+
* [Managing API Keys](#managing-api-keys)
10+
* [Examples and Use Cases](#examples-and-use-cases)
11+
* [License](#license)
12+
13+
14+
<a name="prerequisites-and-installation"></a>
15+
# Prerequisites and Installation
16+
## Prerequisites
17+
* Go 1.2.2 or higher
18+
* 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.
19+
20+
## Installation
21+
```
22+
go get github.com/socketlabs/socketlabs-go/injectionapi
23+
```
24+
25+
26+
<a name="getting-started"></a>
27+
# Getting Started
28+
## Obtaining your API Key and SocketLabs ServerId number
29+
In order to get started, you'll need to enable the Injection API feature in the [SocketLabs Control Panel](https://cp.socketlabs.com).
30+
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).
31+
Make note of your 4 or 5 digit ServerId number, as you'll need this along with
32+
your API key in order to use the Injection API.
33+
34+
To enable the Injection API, click on the "For Developers" dropdown on the top-level navigation, then choose the "Configure HTTP Injection API" option.
35+
Once here, you can enable the feature by choosing the "Enabled" option in the
36+
dropdown. Enabling the feature will also generate your API key, which you'll
37+
need (along with your ServerId) to start using the API. Be sure to click the
38+
"Update" button to save your changes once you are finished.
39+
40+
## Basic Message
41+
A basic message is an email message like you'd send from a personal email client such as Outlook.
42+
A basic message can have many recipients, including multiple To addresses, CC addresses, and even BCC addresses.
43+
You can also send a file attachment in a basic message.
44+
45+
```GO
46+
47+
import (
48+
"github.com/socketlabs/socketlabs-go/injectionapi"
49+
"github.com/socketlabs/socketlabs-go/injectionapi/message"
50+
)
51+
52+
func main() {
53+
client := injectionapi.CreateClient(000001, "YOUR-API-KEY")
54+
55+
basic := message.BasicMessage{}
56+
57+
basic.Subject = "Sending a Basic Message"
58+
basic.HtmlBody = "<html>This is the Html Body of my message.</html>"
59+
basic.PlainTextBody = "This is the Plain Text Body of my message."
60+
61+
basic.From = message.EmailAddress{EmailAddress: "from@example.com"}
62+
basic.ReplyTo = message.EmailAddress{EmailAddress: "replyto@example.com"}
63+
64+
//A basic message supports up to 50 recipients and supports several different ways to add recipients
65+
basic.AddToEmailAddress("recipient@example.com") //Add a To address by passing the email address
66+
basic.AddCcEmailAddress("recipient2@example.com") //Add a CC address by passing the email address and a friendly name
67+
basic.AddBccEmailAddress("recipient3@example.com") //Add a BCC address by passing the email address
68+
69+
//Send the message
70+
_, _ = client.SendBasic(&basic)
71+
}
72+
```
73+
74+
## Bulk Message
75+
A bulk message usually contains a single recipient per message
76+
and is generally used to send the same content to many recipients,
77+
optionally customizing the message via the use of MergeData.
78+
For more information about using Merge data, please see the [Injection API documentation](https://www.socketlabs.com/api-reference/injection-api/#merging).
79+
```GO
80+
import (
81+
"github.com/socketlabs/socketlabs-go/injectionapi"
82+
"github.com/socketlabs/socketlabs-go/injectionapi/message"
83+
)
84+
85+
func main() {
86+
87+
client := injectionapi.CreateClient(000001, "YOUR-API-KEY")
88+
89+
//Build the message
90+
bulk := message.BulkMessage{}
91+
92+
bulk.Subject = "Sending A Bulk Message"
93+
bulk.HtmlBody = "<html>This is the Html Body of my message sent to the recipient with %%EyeColor%% eyes.</html>";
94+
bulk.PlainTextBody = "This is the Plain Text Body of my message sent to the recipient with %%EyeColor%% eyes.";
95+
bulk.From = message.EmailAddress{EmailAddress: "from@example.com"}
96+
bulk.ReplyTo = message.EmailAddress{EmailAddress: "replyto@example.com"}
97+
98+
//Add Bulk Recipients
99+
recipient1 := bulk.AddToFriendlyBulkRecipient("recipient1@example.com", "Recipient #1")
100+
recipient1.AddMergeData("EyeColor", "Green")
101+
102+
recipient2 := bulk.AddToFriendlyBulkRecipient("recipient2@example.com", "Recipient #2")
103+
recipient2.AddMergeData("EyeColor", "Blue")
104+
105+
//Send the message
106+
_, _ = client.SendBulk(&bulk)
107+
}
108+
```
109+
110+
<a name="managing-api-keys"></a>
111+
## Managing API Keys
112+
For ease of demonstration, some of our examples may include the ServerId and 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. In most cases we recommend the use of [Environment Variables](https://flaviocopes.com/golang-environment-variables/).
113+
114+
<a name="examples-and-use-cases"></a>
115+
# Examples and Use Cases
116+
In order to demonstrate the many possible use cases for the SDK, we've provided
117+
an assortment of code examples. These examples demonstrate many different
118+
features available to the Injection API and SDK, including using templates
119+
created in the [SocketLabs Email Designer](https://www.socketlabs.com/blog/introducing-new-email-designer/), custom email headers, sending
120+
attachments, sending content that is stored in an HTML file, advanced bulk
121+
merging, and even pulling recipients from a datasource.
122+
123+
124+
### [Basic send example](https://github.com/socketlabs/socketlabs-go/blob/master/examples/basic/Basic/BasicSend.go)
125+
This example demonstrates a Basic Send.
126+
127+
### [Basic send complex example](https://github.com/socketlabs/socketlabs-go/blob/master/examples/basic/BasicComplex/BasicSendComplex.go)
128+
This example demonstrates many features of the Basic Send, including adding multiple recipients, adding message and mailing id's, and adding an embedded image.
129+
130+
### [Basic send from HTML file](https://github.com/socketlabs/socketlabs-go/blob/master/examples/basic/BasicFromHtmlFile/BasicFromHtmlFile.go)
131+
This example demonstrates how to read in your HTML content from an HTML file
132+
rather than passing in a string directly.
133+
134+
### [Basic send from SocketLabs API Template](https://github.com/socketlabs/socketlabs-go/blob/master/examples/basic/BasicWithApiTemplate/BasicWithApiTemplate.go)
135+
This example demonstrates the sending of a piece of content that was created in the
136+
SocketLabs Email Designer. This is also known as the [API Templates](https://www.socketlabs.com/blog/introducing-api-templates/) feature.
137+
138+
### [Basic send with specified character set](https://github.com/socketlabs/socketlabs-go/blob/master/examples/basic/BasicWithAsciiCharset/BasicWithAsciiCharset.go)
139+
This example demonstrates sending with a specific character set.
140+
141+
### [Basic send with file attachment](https://github.com/socketlabs/socketlabs-go/blob/master/examples/basic/BasicWithAttachment/BasicWithAttachment.go)
142+
This example demonstrates how to add a file attachment to your message.
143+
144+
### [Basic send with custom email headers](https://github.com/socketlabs/socketlabs-go/blob/master/examples/basic/BasicWithCustomHeaders/BasicWithCustomHeaders.go)
145+
This example demonstrates how to add custom headers to your email message.
146+
147+
### [Basic send with embedded image](https://github.com/socketlabs/socketlabs-go/blob/master/examples/basic/BasicWithEmbeddedImage/BasicWithEmbeddedImage.go)
148+
This example demonstrates how to embed an image in your message.
149+
150+
### [Basic send with a web proxy](https://github.com/socketlabs/socketlabs-go/blob/master/examples/basic/BasicSendWithProxy/BasicSendWithProxy.go)
151+
This example demonstrates how to use a proxy with your HTTP client.
152+
153+
154+
### [Basic send with invalid file attachment](https://github.com/socketlabs/socketlabs-go/blob/master/examples/basic/Invalid/BasicWithInvalidAttachment/BasicWithInvalidAttachment.go)
155+
This example demonstrates the results of attempting to do a send with an invalid attachment.
156+
157+
### [Basic send with invalid from address](https://github.com/socketlabs/socketlabs-go/blob/master/examples/basic/Invalid/BasicWithInvalidFrom/BasicWithInvalidFrom.go)
158+
This example demonstrates the results of attempting to do a send with an invalid from address.
159+
160+
### [Basic send with invalid recipients](https://github.com/socketlabs/socketlabs-go/blob/master/examples/basic/Invalid/BasicWithInvalidRecipient/BasicWithInvalidRecipient.go)
161+
This example demonstrates the results of attempting to do a send with invalid recipients.
162+
163+
164+
### [Bulk send with multiple recipients](https://github.com/socketlabs/socketlabs-go/blob/master/examples/bulk/bulk/bulk.go)
165+
This example demonstrates how to send a bulk message to multiple recipients.
166+
167+
### [Bulk send with complex merge including attachments](https://github.com/socketlabs/socketlabs-go/blob/master/examples/bulk/BulkComplex/BulkComplex.go)
168+
This example demonstrates many features of the `BulkMessage()`, including
169+
adding multiple recipients, merge data, and adding an attachment.
170+
171+
### [Bulk send with recipients pulled from a datasource](https://github.com/socketlabs/socketlabs-go/blob/master/examples/bulk/BulkFromDataSourceWithMerge/BulkFromDataSourceWithMerge.go)
172+
This example uses a mock repository class to demonstrate how you would pull
173+
your recipients from a database and create a bulk mailing with merge data.
174+
175+
### [Bulk send with Ascii charset and special characters](https://github.com/socketlabs/socketlabs-go/blob/master/examples/bulk/BulkWithAsciiCharsetMergeData/BulkWithAsciiCharsetMergeData.go)
176+
This example demonstrates how to send a bulk message with a specified character
177+
set and special characters.
178+
179+
### [Bulk send with merge data](https://github.com/socketlabs/socketlabs-go/blob/master/examples/bulk/BulkWithMergeData/BulkWithMergeData.go)
180+
This example demonstrates how to send a bulk message to multiple recipients with
181+
unique merge data per recipient.
182+
183+
184+
<a name="license"></a>
185+
# License
186+
The SocketLabs.EmailDelivery library and all associated code, including any code samples, are [MIT Licensed](https://github.com/socketlabs/socketlabs-go/blob/master/LICENSE.MD).

‎examples/Html/SampleEmail.html

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
<!DOCTYPE html>
2+
3+
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
4+
<head>
5+
<meta charset="utf-8" />
6+
<title>Lorem Ipsum</title>
7+
</head>
8+
<body>
9+
<div>
10+
<h1>Lorem Ipsum</h1>
11+
<h2>The standard Lorem Ipsum passage, used since the 1500s</h2>
12+
<p>
13+
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
14+
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
15+
veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex
16+
ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate
17+
velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat
18+
cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id
19+
est laborum.
20+
</p>
21+
<ol>
22+
<li>Lorem ipsum dolor sit amet, consectetuer adipiscing elit.</li>
23+
<li>Aliquam tincidunt mauris eu risus.</li>
24+
<li>Vestibulum auctor dapibus neque.</li>
25+
</ol>
26+
</div>
27+
</body>
28+
</html>

‎examples/Img/bus.png

487 KB
Loading

‎examples/Integration/Repository/CustomerRepository.go

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
package testdata
2+
3+
// Customer Object to hold customer data for the BulkFromDataSourceWithMerge example
4+
type Customer struct {
5+
FirstName string
6+
LastName string
7+
EmailAddress string
8+
FavoriteColor string
9+
}
10+
11+
// GetCustomers returns a list of mock Customers for the BulkFromDataSourceWithMerge example
12+
func GetCustomers() []Customer {
13+
customer1 := Customer{FirstName: "Recipient", LastName: "One", EmailAddress: "recipient1@example.com", FavoriteColor: "Green"}
14+
customer2 := Customer{FirstName: "Recipient", LastName: "Two", EmailAddress: "recipient2@example.com", FavoriteColor: "Red"}
15+
customer3 := Customer{FirstName: "Recipient", LastName: "Three", EmailAddress: "recipient3@example.com", FavoriteColor: "Blue"}
16+
customer4 := Customer{FirstName: "Recipient", LastName: "Four", EmailAddress: "recipient4@example.com", FavoriteColor: "Orange"}
17+
18+
var list []Customer
19+
list = append(list, customer1, customer2, customer3, customer4)
20+
21+
return list
22+
}

‎examples/basic/Basic/BasicSend.go

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
package main
2+
3+
import (
4+
"fmt"
5+
6+
"github.com/socketlabs/socketlabs-go/examples"
7+
"github.com/socketlabs/socketlabs-go/injectionapi"
8+
"github.com/socketlabs/socketlabs-go/injectionapi/message"
9+
)
10+
11+
func main() {
12+
client := injectionapi.CreateClient(exampleconfig.ServerId(), exampleconfig.APIKey())
13+
14+
basic := message.BasicMessage{}
15+
16+
basic.Subject = "Sending a Basic Message"
17+
basic.HtmlBody = "<html>This is the Html Body of my message.</html>"
18+
basic.PlainTextBody = "This is the Plain Text Body of my message."
19+
20+
basic.From = message.EmailAddress{EmailAddress: "from@example.com"}
21+
basic.ReplyTo = message.EmailAddress{EmailAddress: "replyto@example.com"}
22+
23+
//A basic message supports up to 50 recipients and supports several different ways to add recipients
24+
basic.AddToEmailAddress("recipient@example.com") //Add a To address by passing the email address
25+
basic.AddCcEmailAddress("recipient2@example.com") //Add a CC address by passing the email address and a friendly name
26+
basic.AddBccEmailAddress("recipient3@example.com") //Add a BCC address by passing the email address
27+
28+
//Send the message
29+
sendResponse, _ := client.SendBasic(&basic)
30+
31+
//Output the results
32+
fmt.Println(sendResponse.Result.ToString())
33+
fmt.Println(sendResponse.ResponseMessage)
34+
}

0 commit comments

Comments
 (0)