Skip to content

Commit b9fe290

Browse files
ruboarmruboarm
authored
Merge pull request #2 from PandaTechAM/development
Email and SMS services implementation
2 parents 5c3a7fa + ec7aee0 commit b9fe290

40 files changed

+1359
-104
lines changed

‎Readme.md‎

Lines changed: 300 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,312 @@
1-
# Pandatech.Communicator
1+
# 1. PandaTech.Communicator
22

3-
## Introduction
3+
- [1. EasyRateLimiter](#1-easyratelimiter)
4+
- [1.1. Introduction](#11-introduction)
5+
- [1.2. Installation](#12-installation)
6+
- [1.3. Setup](#13-setup)
7+
- [1.3.1. Program.cs Example](#131-programcs-example)
8+
- [1.3.2. Appsettings.json Example](#132-appsettingsjson-example)
9+
- [1.4. Configuration Options Explained](#14-configuration-options-explained)
10+
- [1.5. Usage](#15-usage)
11+
- [1.5.1. Send SMS message](#151-send-sms-message)
12+
- [1.5.2. Send Email message](#152-send-email-message)
13+
- [1.6. Limitations](#16-limitations)
14+
- [1.7. License](#17-license)
415

5-
This nuget is fake for now. Under development.
16+
## 1.1. Introduction
17+
**PandaTech.Communicator** is aimed to send Email and SMS messages to the clients of your service where you use this library.
618

19+
- **Email:** By given setup it's easy and fast to configure and setup Email providers for later use by different channels.
20+
- **SMS:** By given setup it's easy and fast to configure and setup already integrated SMS providers for later use by different channels.
21+
- **Dexatel**
22+
- **Twilio**
723

8-
## Features
24+
This package is ideal for efficient and reliable messaging in any application.
925

26+
## 1.2. Installation
1027

11-
## Installation
28+
Install this NuGet library directly from the IDE package installer or by following command:
1229

30+
`dotnet add package PandaTech.Communicator`
1331

32+
## 1.3. Setup
1433

15-
## Usage
34+
To incorporate PandaTech.Communicator into your project, you have a primary method to setup in your `Program.cs`:
1635

36+
`builder.AddCommunicator();`
1737

18-
## License
38+
Configuration options can be specified either in `appsettings.json` or directly in `Program.cs`, with the latter taking precedence.
1939

20-
Pandatech.Communicator is licensed under the MIT License.
40+
There are several supported channels which must be kept during setup:
41+
42+
```csharp
43+
EmailChannels
44+
{
45+
"GeneralSender",
46+
"TransactionalSender",
47+
"NotificationSender",
48+
"MarketingSender",
49+
"SupportSender"
50+
};
51+
52+
SmsChannels
53+
{
54+
"GeneralSender",
55+
"TransactionalSender",
56+
"NotificationSender",
57+
"MarketingSender",
58+
"SupportSender"
59+
};
60+
```
61+
62+
For each channel can be setup same provider, but it's recommended to have different sender, as they are dedicated for different purposes.
63+
64+
### 1.3.1. Program.cs Example
65+
66+
In case of using SSL by setting UseSsl = true use port number 456, otherwise use 587 for non SSL connection.
67+
68+
```csharp
69+
builder.AddCommunicator(options =>
70+
{
71+
options.SmsFake = false;
72+
options.SmsConfigurations = new Dictionary<string, SmsConfiguration>
73+
{
74+
{
75+
"GeneralSender", new SmsConfiguration
76+
{
77+
Provider = "Dexatel",
78+
From = "sender_name",
79+
Properties = new Dictionary<string, string>
80+
{
81+
{ "X-Dexatel-Key", "key" }
82+
},
83+
TimeoutMs = 10000
84+
}
85+
},
86+
{
87+
"TransactionalSender", new SmsConfiguration
88+
{
89+
Provider = "Twilio",
90+
From = "sender_number",
91+
Properties = new Dictionary<string, string>
92+
{
93+
{ "SID", "key" },
94+
{ "AUTH_TOKEN", "token" }
95+
},
96+
TimeoutMs = 10000
97+
}
98+
}
99+
};
100+
options.EmailFake = false;
101+
options.EmailConfigurations = new Dictionary<string, EmailConfiguration>
102+
{
103+
{
104+
"GeneralSender", new EmailConfiguration
105+
{
106+
SmtpServer = "smtp.test.com",
107+
SmtpPort = 465, // 587
108+
SmtpUsername = "test",
109+
SmtpPassword = "test123",
110+
SenderEmail = "[email protected]",
111+
UseSsl = true, // false
112+
TimeoutMs = 10000
113+
}
114+
},
115+
{
116+
"TransactionalSender", new EmailConfiguration
117+
{
118+
SmtpServer = "smtp.gmail.com",
119+
SmtpPort = 465, // 587
120+
SmtpUsername = "vazgen",
121+
SmtpPassword = "vazgen123",
122+
SenderEmail = "[email protected]",
123+
UseSsl = true, // false
124+
TimeoutMs = 10000
125+
}
126+
}
127+
};
128+
});
129+
130+
```
131+
132+
### 1.3.2. Appsettings.json Example
133+
134+
```json
135+
{
136+
"Logging": {
137+
"LogLevel": {
138+
"Default": "Information",
139+
"Microsoft.AspNetCore": "Warning"
140+
}
141+
},
142+
"Communicator": {
143+
"SmsFake": false,
144+
"SmsConfigurations": {
145+
"GeneralSender": {
146+
"Provider": "Dexatel",
147+
"From": "sender_name",
148+
"Properties": {
149+
"X-Dexatel-Key": "key"
150+
},
151+
"TimeoutMs": "10000"
152+
},
153+
"TransactionalSender": {
154+
"Provider": "Twilio",
155+
"From": "sender_number",
156+
"Properties": {
157+
"SID": "key",
158+
"AUTH_TOKEN": "token"
159+
},
160+
"TimeoutMs": "10000"
161+
}
162+
},
163+
"EmailFake": false,
164+
"EmailConfigurations": {
165+
"GeneralSender": {
166+
"SmtpServer": "smtp.gmail.com",
167+
"SmtpPort": 465, // 587
168+
"SmtpUsername": "vazgen",
169+
"SmtpPassword": "vazgen123",
170+
"SenderEmail": "[email protected]",
171+
"UseSsl": true, // false
172+
"TimeoutMs": "10000"
173+
},
174+
"TransactionalSender": {
175+
"SmtpServer": "smtp.gmail.com",
176+
"SmtpPort": 465, // 587
177+
"SmtpUsername": "vazgen",
178+
"SmtpPassword": "vazgen123",
179+
"SenderEmail": "[email protected]",
180+
"UseSsl": true, // false
181+
"TimeoutMs": "10000"
182+
}
183+
}
184+
}
185+
}
186+
```
187+
The configuration options in `appsettings.json` and `program.cs` (priority) are identical.
188+
189+
## 1.4. Configuration Options Explained
190+
191+
- **Communicator:** Global settings for PandaTech.Communicator
192+
- **SmsFake:** This setup is for fake SMS service to be used which doesn't send real SMS messages and just return `TTask.CompletedTask`.
193+
- **SmsConfigurations:** SMS configurations given by `appsettings.json` or via `builder.AddCommunicator()` options for SMS.
194+
- **EmailFake:** This setup is for fake Email service to be used which doesn't send real SMS messages and just return `TTask.CompletedTask`.
195+
- **EmailConfigurations:** Email configurations given by `appsettings.json` or via `builder.AddCommunicator()` options for Email.
196+
197+
## 1.5. Usage
198+
199+
In order to use the library, you need to generate `SmsMessage` or `EmailMessage` and use one of the interfaces mentioned above for the service you need to use.
200+
201+
Both of them support multiple recipients.
202+
203+
The structure of the messages are shown below.
204+
205+
```csharp
206+
public class SmsMessage
207+
{
208+
public List<string> Recipients { get; set; } = null!;
209+
public string Message { get; set; } = null!;
210+
public string Channel { get; set; } = null!;
211+
}
212+
213+
public class EmailMessage
214+
{
215+
public List<string> Recipients { get; set; } = null!;
216+
public string Subject { get; set; } = null!;
217+
public string Body { get; set; } = null!;
218+
public List<string> Cc { get; set; } = [];
219+
public List<string> Bcc { get; set; } = [];
220+
public List<EmailAttachment> Attachments { get; set; } = [];
221+
public bool IsBodyHtml { get; set; } = false;
222+
public string Channel { get; set; } = null!;
223+
}
224+
```
225+
226+
Channel is set by `EmailChannels` or by `SmsChannels` classes with constant values.
227+
228+
There are 2 interfaces `ISmsService` and `IEmailService` responsible for individual cases SMS or Email.
229+
Methods for sending SMS/Email messages are:
230+
- **SendAsync:**
231+
- **SendBulkAsync:**
232+
233+
The structure of the service interfaces are shown below.
234+
235+
```csharp
236+
public interface ISmsService
237+
{
238+
Task<List<GeneralSmsResponse>> SendAsync(SmsMessage smsMessage, CancellationToken cancellationToken = default);
239+
Task<List<GeneralSmsResponse>> SendBulkAsync(List<SmsMessage> smsMessageList, CancellationToken cancellationToken = default);
240+
}
241+
242+
public interface IEmailService
243+
{
244+
Task<GeneralEmailResponse> SendAsync(EmailMessage emailMessage, CancellationToken cancellationToken = default);
245+
Task<List<GeneralEmailResponse>> SendBulkAsync(List<EmailMessage> emailMessages, CancellationToken cancellationToken = default);
246+
}
247+
```
248+
249+
## 1.5.1. Send SMS message
250+
251+
```csharp
252+
var sms = new SmsMessage
253+
{
254+
Recipients = ["+37493910593"],
255+
Message = "123456",
256+
Channel = SmsChannels.GeneralSender
257+
};
258+
await smsService.SendAsync(sms);
259+
```
260+
261+
Sms service returns general response which includes general properties in already integrated services.
262+
263+
Both methods return `List<GeneralSmsResponse>` when you use them while sending sms.
264+
If you set a variable to the call, you will be able to use returned response.
265+
266+
```csharp
267+
public class GeneralSmsResponse
268+
{
269+
public string From { get; set; } = null!;
270+
public string To { get; set; } = null!;
271+
public string OuterSmsId { get; set; } = null!;
272+
public string Status { get; set; } = null!;
273+
public DateTime CreateDate { get; set; }
274+
public DateTime UpdateDate { get; set; }
275+
public string Body { get; set; } = null!;
276+
}
277+
```
278+
279+
## 1.5.2. Send Email message
280+
281+
```csharp
282+
var email = new EmailMessage
283+
{
284+
Recipients = ["[email protected]"],
285+
Subject = "Some subject",
286+
Body = "Some body",
287+
IsBodyHtml = false,
288+
Channel = EmailChannels.GeneralSender
289+
};
290+
await emailService.SendAsync(email);
291+
```
292+
Both methods return response (SendAsync - `GeneralEmailResponse`; SendBulkAsync - `List<GeneralEmailResponse>`) when you use them while sending email.
293+
If you set a variable to the call, you will be able to use returned response.
294+
295+
```csharp
296+
public class GeneralEmailResponse
297+
{
298+
public string Status { get; set; } = null!;
299+
public string Code { get; set; } = null!;
300+
public string TrackingId { get; set; } = null!;
301+
public string Id { get; set; } = null!;
302+
public string Service { get; set; } = null!;
303+
}
304+
```
305+
306+
## 1.6. Limitations
307+
308+
PandaTech.Communicator works with all Email providers, but with only with existing integrations for SMS listed above.
309+
310+
## 1.7. License
311+
312+
PandaTech.Communicator is licensed under the MIT License.

0 commit comments

Comments
 (0)