106 lines
3.8 KiB
Markdown
106 lines
3.8 KiB
Markdown
## Cakemail SDK for .NET
|
|
|
|
This SDK provides a convenient way to interact with the Cakemail API from your .NET applications.
|
|
|
|
### Installation
|
|
|
|
You can install the Cakemail SDK via NuGet Package Manager:
|
|
|
|
```bash
|
|
Install-Package Cakemail.SDK
|
|
```
|
|
|
|
### Configuration
|
|
|
|
The SDK relies on configuration settings typically found in your `appsettings.json` file. Here's an example of the required `Cakemail` section:
|
|
|
|
```json
|
|
"Cakemail": {
|
|
"Authentication": {
|
|
"TokenEndpoint": "YOUR_CAKEMAIL_TOKEN_ENDPOINT",
|
|
"Username": "YOUR_CAKEMAIL_USERNAME",
|
|
"Password": "YOUR_CAKEMAIL_PASSWORD",
|
|
"Cache": {
|
|
"ExpirationOffset": 15,
|
|
"CacheKey": "CakemailJwtTokenManager.JwtTokenResult"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Important:** Replace `"YOUR_CAKEMAIL_TOKEN_ENDPOINT"`, `"YOUR_CAKEMAIL_USERNAME"`, and `"YOUR_CAKEMAIL_PASSWORD"` with your actual Cakemail API credentials.
|
|
|
|
### Service Configuration
|
|
|
|
To integrate the Cakemail SDK into your .NET application's dependency injection container, you'll need to configure the services in your `Startup.cs` or `Program.cs` file.
|
|
|
|
```csharp
|
|
services.AddMemoryCache(); // Add to reuse the same Jwt token until it expires
|
|
services.AddHttpClient(); // Required for making HTTP requests
|
|
services.AddCakemailSdk(); // Adds Cakemail SDK services
|
|
```
|
|
|
|
* `services.AddMemoryCache()`: This is highly recommended to cache the JWT token obtained from Cakemail, preventing repeated authentication requests and improving performance.
|
|
* `services.AddHttpClient()`: This registers the necessary `HttpClient` services for the SDK to make API calls.
|
|
* `services.AddCakemailSdk()`: This extension method registers all the necessary Cakemail SDK services, including various API clients, with your dependency injection container.
|
|
|
|
### Usage
|
|
|
|
The Cakemail SDK provides various services for interacting with different aspects of the Cakemail API. Here's an example of how to use the `TransactionalEmailService` to send an email:
|
|
|
|
```csharp
|
|
public class MyService
|
|
{
|
|
private readonly TransactionalEmailService _transactionalEmailService;
|
|
|
|
public MyService(TransactionalEmailService transactionalEmailService)
|
|
{
|
|
_transactionalEmailService = transactionalEmailService;
|
|
}
|
|
|
|
public async Task SendEmailAsync(string senderId, string recipient, string subject, string message)
|
|
{
|
|
await _transactionalEmailService.SendEmailAsync(new SendEmailOptions
|
|
{
|
|
Email = recipient,
|
|
Sender = new Sender
|
|
{
|
|
Id = senderId
|
|
},
|
|
Content = new EmailContent
|
|
{
|
|
Subject = subject,
|
|
Text = message,
|
|
Encoding = EmailEncoding.Utf8,
|
|
},
|
|
Tracking = new TrackingOptions
|
|
{
|
|
ClicksHtml = false, // Set to true to track clicks on HTML links
|
|
ClicksText = false, // Set to true to track clicks on text links
|
|
Opens = true // Set to true to track email opens
|
|
},
|
|
Queue = 0 // Optional: The queue ID to use for sending the email
|
|
});
|
|
}
|
|
}
|
|
```
|
|
|
|
In this example:
|
|
|
|
1. The `MyService` class injects the `TransactionalEmailService`.
|
|
2. The `SendEmailAsync` method demonstrates how to construct a `SendEmailOptions` object with the recipient, sender, email content (subject, text, encoding), and tracking options.
|
|
3. `EmailEncoding.Utf8` is a common encoding for email content.
|
|
4. `TrackingOptions` allow you to control whether email opens and clicks are tracked.
|
|
|
|
### Available Services
|
|
|
|
The Cakemail SDK provides dedicated services for different API functionalities. You can inject these services into your classes as needed:
|
|
|
|
* `TransactionalEmailService`: For sending transactional emails.
|
|
|
|
### Resources
|
|
* [Cakemail](https://www.cakemail.com/index.html)
|
|
* [Cakemail API Documentation](https://cakemail.dev/api)
|
|
|
|
### License MIT
|