CM.EmailGateway
2.1.0
dotnet add package CM.EmailGateway --version 2.1.0
NuGet\Install-Package CM.EmailGateway -Version 2.1.0
<PackageReference Include="CM.EmailGateway" Version="2.1.0" />
<PackageVersion Include="CM.EmailGateway" Version="2.1.0" />
<PackageReference Include="CM.EmailGateway" />
paket add CM.EmailGateway --version 2.1.0
#r "nuget: CM.EmailGateway, 2.1.0"
#:package CM.EmailGateway@2.1.0
#addin nuget:?package=CM.EmailGateway&version=2.1.0
#tool nuget:?package=CM.EmailGateway&version=2.1.0
CM Email Gateway .NET SDK
A .NET SDK for integrating with the CM Email Gateway API, providing a simple and robust way to send marketing and transactional emails.
Installation
NuGet Package
dotnet add package CM.EmailGateway
Manual Installation
Clone the repository and build the project:
git clone https://github.com/cmdotcom/email-gateway-api-sdk.git
cd email-gateway-api-sdk/dotnet
dotnet build
Quick Start
Basic Marketing Email
using CM.Email.GateWayApi.SDK;
using CM.Email.GateWayApi.SDK.Exceptions;
// Initialize the client
var client = new EmailGatewayClient("YOUR_PRODUCT_TOKEN", sandboxMode: true);
// Prepare email request as JSON
var jsonRequest = """
{
"from": {
"email": "sender@example.com",
"name": "Marketing Team"
},
"to": [
{
"email": "recipient@example.com",
"name": "John Doe"
}
],
"subject": "Welcome to our service!",
"html": "<html><body><h1>Welcome!</h1></body></html>",
"text": "Welcome to our service!"
}
""";
try
{
var response = await client.SendMarketingEmailAsync(jsonRequest);
Console.WriteLine($"Email sent! MessageId: {response.MessageId}");
}
catch (EmailGatewayException ex)
{
Console.WriteLine($"Error: {ex.Message} (Status: {ex.StatusCode})");
}
Transactional Email with Priority
var jsonRequest = """
{
"from": {
"email": "noreply@example.com",
"name": "System Notifications"
},
"to": [
{
"email": "user@example.com",
"name": "User Name"
}
],
"subject": "Your Order Confirmation",
"html": "<h1>Order Confirmed</h1>",
"customerReference": "ORDER-12345"
}
""";
// Send with high priority
var response = await client.SendTransactionalEmailAsync(jsonRequest, "high");
EmailGatewayClient
Constructor
public EmailGatewayClient(string ProductToken, bool SandboxMode = false, string? BaseUrlOverride = null)
Parameters:
ProductToken(string, required): Your CM Email Gateway product tokenSandboxMode(bool, optional): Enable sandbox mode for testing (default: false)BaseUrlOverride(string, optional): Custom base URL for the API endpoint
Methods
SendMarketingEmailAsync
public async Task<EmailResponse> SendMarketingEmailAsync(string jsonRequest)
Sends a marketing email.
Parameters:
jsonRequest(string): JSON string containing the email request
Returns: Task<EmailResponse>
Throws: EmailGatewayException
SendTransactionalEmailAsync
public async Task<EmailResponse> SendTransactionalEmailAsync(string jsonRequest, string priority)
Sends a transactional email with specified priority.
Parameters:
jsonRequest(string): JSON string containing the email requestpriority(string): Priority level - "high" or "low"
Returns: Task<EmailResponse>
Throws: EmailGatewayException
Email Request Structure
EmailRequest JSON Schema
{
"from": {
"email": "sender@example.com",
"name": "Sender Name"
},
"replyTo": {
"email": "reply@example.com",
"name": "Reply Name"
},
"to": [
{
"email": "recipient@example.com",
"name": "Recipient Name"
}
],
"cc": [
{
"email": "cc@example.com",
"name": "CC Name"
}
],
"bcc": [
{
"email": "bcc@example.com",
"name": "BCC Name"
}
],
"subject": "Email Subject",
"html": "<html><body>HTML content</body></html>",
"text": "Plain text content",
"attachments": [
{
"filename": "document.pdf",
"content": "base64EncodedContent",
"contentType": "application/pdf",
"contentId": "unique-id"
}
],
"customerReference": "YOUR-REFERENCE-ID",
"scheduledAt": "2026-10-22T15:30:00-08:00",
"inReplyTo": "<original-message-id@example.com>",
"references": "<first-message-id@example.com> <original-message-id@example.com>",
"headers": {
"X-Campaign-Id": "spring-sale"
}
}
scheduledAt is optional and delays delivery. It must be an ISO 8601 date-time with an offset (e.g. 2026-10-22T15:30:00-08:00 or ...Z), in the future and no more than 72 hours ahead; otherwise the API rejects the request.
inReplyTo and references are optional and set the In-Reply-To / References headers so mail clients group the message into an existing conversation. Each must be at most 998 characters with no line breaks. headers accepts up to 20 custom headers (letters, digits and hyphens in names, printable ASCII values); reserved headers such as From, To, Subject and Message-ID are rejected.
var response = await client.SendTransactionalEmailAsync(new EmailRequest
{
From = new EmailAddress { Email = "sender@example.com" },
To = [new EmailAddress { Email = "recipient@example.com" }],
Subject = "Re: Your order",
Text = "Thanks for your reply.",
InReplyTo = "<original-message-id@example.com>",
References = "<first-message-id@example.com> <original-message-id@example.com>",
Headers = new Dictionary<string, string> { ["X-Order-Id"] = "12345" }
}, TransactionalPriority.High);
Response Structure
EmailResponse
public class EmailResponse
{
public int Status { get; set; }
public string Message { get; set; }
public bool Success { get; set; }
public string MessageId { get; set; }
}
Example Success Response:
{
"status": 200,
"message": "Email sent successfully",
"success": true,
"messageId": "abc123-def456-ghi789"
}
Configuration
Sandbox Mode
Enable sandbox mode for testing without sending real emails:
var client = new EmailGatewayClient("YOUR_TOKEN", sandboxMode: true);
Custom Base URL
Override the default API endpoint if you need to use a different environment:
var client = new EmailGatewayClient(
"YOUR_TOKEN",
sandboxMode: false,
baseUrlOverride: "https://custom-api.example.com/email/gateway"
);
Priority Levels
For transactional emails, three priority levels are available:
- high: Urgent emails
- low: Non-urgent notifications
Requirements
- .NET 8.0 or later
- Valid CM Email Gateway product token
Dependencies
- Microsoft.Extensions.Http (>= 8.0.0)
- System.Text.Json (>= 8.0.5)
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net9.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.2)
- Microsoft.Extensions.Http (>= 8.0.0)
- System.Text.Json (>= 8.0.5)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.