Skip to content

Commit 946d077

Browse files
david-schrenkerdavid-schrenker
committed
initial commit
1 parent 2cb9434 commit 946d077

Some content is hidden

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

63 files changed

+5064
-2
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
*.gem
22
*.rbc
3+
*.zip
34
/.config
45
/coverage/
56
/InstalledFiles

‎.idea/inspectionProfiles/Project_Default.xml‎

Lines changed: 7 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎.idea/misc.xml‎

Lines changed: 7 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎.idea/modules.xml‎

Lines changed: 8 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎.idea/socketlabs-ruby.iml‎

Lines changed: 12 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎.idea/vcs.xml‎

Lines changed: 7 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎.idea/workspace.xml‎

Lines changed: 451 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎LICENSE‎ renamed to ‎LICENSE.MD‎

File renamed without changes.

‎README.MD‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
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 Ruby 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 Ruby version (2.4 and above)
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+
Add this line to your application's Gemfile:
26+
```ruby
27+
gem 'socketlabs-injectionapi'
28+
```
29+
And then execute:
30+
31+
$ bundle install
32+
33+
Install it yourself as:
34+
35+
$ gem install socketlabs-injectionapi
36+
37+
Or From git
38+
39+
$ gem 'socketlabs-injectionapi', :git => "https://github.com/socketlabs/socketlabs-ruby.git"
40+
41+
42+
For more information please see the [Installing Gems](https://guides.rubygems.org/rubygems-basics/) tutorial
43+
44+
<a name="getting-started" id="getting-started"></a>
45+
# Getting Started
46+
## Obtaining your API Key and SocketLabs ServerId number
47+
In order to get started, you'll need to enable the Injection API feature in the [SocketLabs Control Panel](https://cp.socketlabs.com).
48+
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).
49+
Make note of your 4 or 5 digit ServerId number, as you'll need this along with
50+
your API key in order to use the Injection API.
51+
52+
To enable the Injection API, click on the "For Developers" dropdown on the top-level navigation, then choose the "Configure HTTP Injection API" option.
53+
Once here, you can enable the feature by choosing the "Enabled" option in the
54+
dropdown. Enabling the feature will also generate your API key, which you'll
55+
need (along with your ServerId) to start using the API. Be sure to click the
56+
"Update" button to save your changes once you are finished.
57+
58+
59+
## Basic Message
60+
A basic message is an email message like you'd send from a personal email client such as Outlook.
61+
A basic message can have many recipients, including multiple To addresses, CC addresses, and even BCC addresses.
62+
You can also send a file attachment in a basic message.
63+
64+
```ruby
65+
require "socketlabs-injectionapi"
66+
67+
include SocketLabs::InjectionApi
68+
include SocketLabs::InjectionApi::Message
69+
70+
message = BasicMessage.new
71+
72+
message.subject = "Sending A Basic Message"
73+
message.html_body = "<html>This is the Html Body of my message.</html>"
74+
message.plain_text_body = "This is the Plain Text Body of my message."
75+
76+
message.from_email_address = EmailAddress.new("[email protected]")
77+
78+
# A basic message supports up to 50 recipients
79+
# and supports several different ways to add recipients
80+
81+
# Add a To address by passing the email address
82+
message.to_email_address.push("[email protected]")
83+
message.to_email_address.push(EmailAddress.new("[email protected]", "Recipient #2"))
84+
85+
# // Adding CC Recipients
86+
message.add_cc_email_address("[email protected]")
87+
message.add_cc_email_address("[email protected]", "Recipient #4")
88+
89+
# Adding Bcc Recipients
90+
message.add_bcc_email_address(EmailAddress.new("[email protected]"))
91+
message.add_bcc_email_address(EmailAddress.new("[email protected]", "Recipient #6"))
92+
93+
# Your SocketLabs ServerId and Injection API key
94+
client = SocketLabsClient.new(10000, "YOUR-API-KEY")
95+
96+
response = client.send(message)
97+
```
98+
99+
## Bulk Message
100+
A bulk message usually contains a single recipient per message
101+
and is generally used to send the same content to many recipients,
102+
optionally customizing the message via the use of MergeData.
103+
For more information about using Merge data, please see the [Injection API documentation](https://www.socketlabs.com/api-reference/injection-api/#merging).
104+
```ruby
105+
require "socketlabs-injectionapi"
106+
107+
include SocketLabs::InjectionApi
108+
include SocketLabs::InjectionApi::Message
109+
110+
# Your SocketLabs ServerId and Injection API key
111+
client = SocketLabsClient.new(10000, "YOUR-API-KEY")
112+
113+
message = BulkMessage.new
114+
115+
message.subject = "Sending A Bulk Message"
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+
119+
message.from_email_address = EmailAddress.new("[email protected]")
120+
121+
message.add_global_merge_data("HairColor", "{ not set }")
122+
123+
recipient1 = BulkRecipient.new("[email protected]")
124+
recipient1.add_merge_data("Name", "Recipient1")
125+
message.add_to_recipient(recipient1)
126+
127+
recipient2 = BulkRecipient.new("[email protected]", { :friendly_name => "Recipient #2" })
128+
recipient2.add_merge_data("Name", "Recipient2")
129+
message.add_to_recipient(recipient2)
130+
131+
response = client.send(message)
132+
```
133+
134+
<a name="managing-api-keys" id="managing-api-keys"></a>
135+
## Managing API Keys
136+
For ease of demonstration, many of our examples include the ServerId (SOCKETLABS_SERVER_ID) and API key
137+
(SOCKETLABS_INJECTION_API_KEY) directly in our code sample. Generally it is not considered a good practice to store
138+
sensitive information like this directly in your code. Depending on your project type, we recommend either storing your
139+
credentials using Environment Variables. For more information please see:
140+
[Using Environment Variables](https://docs.microsoft.com/en-us/dotnet/api/system.environment.getenvironmentvariable)
141+
142+
143+
<a name="examples-and-use-cases" id="examples-and-use-cases"></a>
144+
# Examples and Use Cases
145+
In order to demonstrate the many possible use cases for the SDK, we've provided
146+
an assortment of code examples. These examples demonstrate many different
147+
features available to the Injection API and SDK, including using templates
148+
created in the [SocketLabs Email Designer](https://www.socketlabs.com/blog/introducing-new-email-designer/), custom email headers, sending
149+
attachments, sending content that is stored in an HTML file, advanced bulk
150+
merging, and even pulling recipients from a datasource.
151+
152+
### [Basic send example](https://github.com/socketlabs/socketlabs-ruby/blob/master/examples/basic/basic_send.rb)
153+
This example demonstrates a Basic Send.
154+
155+
### [Basic send complex example](https://github.com/socketlabs/socketlabs-ruby/blob/master/examples/basic/basic_send_complex.rb)
156+
This example demonstrates many features of the Basic Send, including adding multiple recipients, adding message and mailing id's, and adding an embedded image.
157+
158+
### [Basic send from HTML file](https://github.com/socketlabs/socketlabs-ruby/blob/master/examples/basic/basic_send_from_html_file.rb)
159+
This example demonstrates how to read in your HTML content from an HTML file
160+
rather than passing in a string directly.
161+
162+
### [Basic send from SocketLabs Template](https://github.com/socketlabs/socketlabs-ruby/blob/master/examples/basic/basic_send_with_api_template.rb)
163+
This example demonstrates the sending of a piece of content that was created in the
164+
SocketLabs Email Designer. This is also known as the [API Templates](https://www.socketlabs.com/blog/introducing-api-templates/) feature.
165+
166+
### [Basic send with specified character set](https://github.com/socketlabs/socketlabs-ruby/blob/master/examples/basic/basic_send_with_ascii_charset.rb)
167+
This example demonstrates sending with a specific character set.
168+
169+
### [Basic send with file attachment](https://github.com/socketlabs/socketlabs-ruby/blob/master/examples/basic/basic_send_with_attachment.rb)
170+
This example demonstrates how to add a file attachment to your message.
171+
172+
### [Basic send with custom email headers](https://github.com/socketlabs/socketlabs-ruby/blob/master/examples/basic/basic_send_with_custom_headers.rb)
173+
This example demonstrates how to add custom headers to your email message.
174+
175+
### [Basic send with embedded image](https://github.com/socketlabs/socketlabs-ruby/blob/master/examples/basic/basic_send_with_embedded_image.rb)
176+
This example demonstrates how to embed an image in your message.
177+
178+
### [Basic send with a web proxy](https://github.com/socketlabs/socketlabs-ruby/blob/master/examples/basic/basic_send_with_proxy.rb)
179+
This example demonstrates how to use a proxy with your HTTP client.
180+
181+
### [Basic send with invalid file attachment](https://github.com/socketlabs/socketlabs-ruby/blob/master/examples/basic/invalid/basic_send_with_invalid_attachment.rb)
182+
This example demonstrates the results of attempting to do a send with an invalid attachment.
183+
184+
### [Basic send with invalid from address](https://github.com/socketlabs/socketlabs-ruby/blob/master/examples/basic/invalid/basic_send_with_invalid_from.rb)
185+
This example demonstrates the results of attempting to do a send with an invalid from address.
186+
187+
### [Basic send with invalid recipients](https://github.com/socketlabs/socketlabs-ruby/blob/master/examples/basic/invalid/basic_send_with_invalid_recipients.rb)
188+
This example demonstrates the results of attempting to do a send with invalid recipients.
189+
190+
### [Bulk send with multiple recipients](https://github.com/socketlabs/socketlabs-ruby/blob/master/examples/bulk/bulk_send.rb)
191+
This example demonstrates how to send a bulk message to multiple recipients.
192+
193+
### [Bulk send with merge data](https://github.com/socketlabs/socketlabs-ruby/blob/master/examples/bulk/bulk_send_with_merge_data.rb)
194+
This example demonstrates how to send a bulk message to multiple recipients with
195+
unique merge data per recipient.
196+
197+
### [Bulk send with complex merge including attachments](https://github.com/socketlabs/socketlabs-ruby/blob/master/examples/bulk/bulk_send_complex.rb)
198+
This example demonstrates many features of the `BulkMessage()`, including
199+
adding multiple recipients, merge data, and adding an attachment.
200+
201+
### [Bulk send with recipients pulled from a datasource](https://github.com/socketlabs/socketlabs-ruby/blob/master/examples/bulk/bulk_send_from_data_source_with_merge_data.rb)
202+
This example uses a mock repository class to demonstrate how you would pull
203+
your recipients from a database and create a bulk mailing with merge data.
204+
205+
### [Bulk send with Ascii charset and special characters](https://github.com/socketlabs/socketlabs-ruby/blob/master/examples/bulk/bulk_send_with_ascii_charset_merge_data.rb)
206+
This example demonstrates how to send a bulk message with a specified character
207+
set and special characters.
208+
209+
210+
<a name="license" id="license"></a>
211+
# License
212+
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).

‎README.md‎

Lines changed: 0 additions & 2 deletions
This file was deleted.

0 commit comments

Comments
 (0)