Getting Started

This guide walks you through installing and configuring the Secure Exchanges SDK.

Prerequisites

• Visual Studio 2019+ or Visual Studio Code with C# extension
• .NET Framework 4.7.2+ or .NET 8.0+ (see package table below)
• Secure Exchanges License with API access
• Internet connection to communicate with Secure Exchanges servers

Installation

Choose the package that matches your target framework:

Target framework	Main SDK	Signature SDK (optional)
.NET Framework 4.7.2+ (Windows only)	SecureExchanges	SecureExchanges.Signature
.NET 8+ (Windows + Linux)	SecureExchanges.NetCore	SecureExchanges.Signature.NetCore

Note

The .NetCore variant is required to deploy on Linux (e.g. Azure Functions Linux containers). For the Signature SDK specifics, see PDF Certification.

.NET Framework

Install-Package SecureExchanges

.NET 8+ / .NET Core

Install-Package SecureExchanges.NetCore

Via .NET CLI

# .NET Framework
dotnet add package SecureExchanges

# .NET 8+ / .NET Core
dotnet add package SecureExchanges.NetCore

Via PackageReference

<!-- .NET Framework -->
<PackageReference Include="SecureExchanges" Version="*" />

<!-- .NET 8+ / .NET Core -->
<PackageReference Include="SecureExchanges.NetCore" Version="*" />

Obtaining API Credentials

Step 1: Portal Login

1. Access the Secure Exchanges portal
2. Log in with an administrator account or the API account

Step 2: Access User Management

1. Click Account in the menu
2. Select Options > User Management

Step 3: Assign API License

1. Locate the user who will use the API
2. Click the Manage Licenses icon
3. Assign an API license to this user
4. Click Save

Step 4: Generate Keys

1. Click the API Key icon (next to the user)
2. A secure message containing your credentials will be sent
3. A password will be provided to open this message

Important

The message containing your keys expires after 15 minutes. Open it quickly and store your credentials securely.

Your Credentials

You will receive three values:

Credential	Description
Serial	Your license serial number (GUID)
API User	API user identifier (GUID)
API Password	API password (GUID)

Basic Configuration

Minimal Configuration

using System;
using SecureExchangesSDK.Helpers;
using SecureExchangesSDK.Models.Args;
using SecureExchangesSDK.Models.Entity;

public class SecureExchangesConfig
{
    // Your API credentials
    public static Guid Serial = new Guid("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX");
    public static Guid ApiUser = new Guid("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX");
    public static Guid ApiPassword = new Guid("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX");

    // Endpoint (production or preview for testing)
    public static Uri Endpoint = new Uri("https://www.secure-exchanges.com/_api/0217/0217.asmx");
}

Configuration via App.config

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="SecureExchanges:Serial" value="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" />
    <add key="SecureExchanges:ApiUser" value="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" />
    <add key="SecureExchanges:ApiPassword" value="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" />
    <add key="SecureExchanges:Endpoint" value="https://www.secure-exchanges.com/_api/0217/0217.asmx" />
  </appSettings>
</configuration>

using System.Configuration;

public class SecureExchangesConfig
{
    public static Guid Serial => new Guid(ConfigurationManager.AppSettings["SecureExchanges:Serial"]);
    public static Guid ApiUser => new Guid(ConfigurationManager.AppSettings["SecureExchanges:ApiUser"]);
    public static Guid ApiPassword => new Guid(ConfigurationManager.AppSettings["SecureExchanges:ApiPassword"]);
    public static Uri Endpoint => new Uri(ConfigurationManager.AppSettings["SecureExchanges:Endpoint"]);
}

Warning

Never store your API credentials in plain text in source code. Use environment variables or a secrets manager.

First Test: License Verification

using SecureExchangesSDK.Helpers;

// Verify that the license is valid
bool isValid = LicenceHelper.IsLicenceIsValid(
    SecureExchangesConfig.Endpoint,
    SecureExchangesConfig.Serial,
    SecureExchangesConfig.ApiUser,
    SecureExchangesConfig.ApiPassword
);

if (isValid)
{
    Console.WriteLine("Valid license! Configuration is correct.");
}
else
{
    Console.WriteLine("Invalid license. Check your credentials.");
}

Sending Your First Message

Quick Version

using SecureExchangesSDK.Helpers;
using SecureExchangesSDK.Models.Args;
using SecureExchangesSDK.Models.Entity;
using SecureExchangesSDK.SecureExchanges;

// Recipient
var recipients = new List<RecipientInfo>
{
    new RecipientInfo { Email = "recipient@example.com" }
};

// Endpoint
Uri endpoint = new Uri("https://www.secure-exchanges.com/_api/0217/0217.asmx");

// Send
var args = new MutliRecipientArgs(
    endpoint, Serial, ApiUser, ApiPassword,
    recipients, "My secure message", "Subject",
    null, null, SendMethodEnum.onlyEmail,
    false, true, true, "en-CA", 5, 1440
);

var response = MessageHelper.MultiRecipientMessage(args);
Console.WriteLine(response.Status == 200 ? "Sent!" : response.Data);

Complete Version with Error Handling

using System;
using System.Collections.Generic;
using SecureExchangesSDK.Helpers;
using SecureExchangesSDK.Models.Args;
using SecureExchangesSDK.Models.Answer;
using SecureExchangesSDK.Models.Entity;
using SecureExchangesSDK.SecureExchanges;

public class MessageService
{
    private readonly Guid _serial;
    private readonly Guid _apiUser;
    private readonly Guid _apiPassword;
    private readonly Uri _endpoint;

    private static readonly Uri DefaultEndpoint = new Uri("https://www.secure-exchanges.com/_api/0217/0217.asmx");

    public MessageService(Guid serial, Guid apiUser, Guid apiPassword, Uri endpoint = null)
    {
        _serial = serial;
        _apiUser = apiUser;
        _apiPassword = apiPassword;
        _endpoint = endpoint ?? DefaultEndpoint;
    }

    /// <summary>
    /// Sends a secure message to a recipient
    /// </summary>
    /// <param name="recipientEmail">Recipient's email</param>
    /// <param name="subject">Message subject</param>
    /// <param name="htmlBody">Message body (HTML allowed)</param>
    /// <param name="password">Optional password to protect the message</param>
    /// <returns>Message URL if successful, null otherwise</returns>
    public string SendSecureMessage(
        string recipientEmail,
        string subject,
        string htmlBody,
        string password = null)
    {
        try
        {
            // Parameter validation
            if (string.IsNullOrWhiteSpace(recipientEmail))
                throw new ArgumentException("Recipient email is required");
            if (string.IsNullOrWhiteSpace(subject))
                throw new ArgumentException("Subject is required");
            if (string.IsNullOrWhiteSpace(htmlBody))
                throw new ArgumentException("Message body is required");

            // Create recipient list
            var recipients = new List<RecipientInfo>
            {
                new RecipientInfo { Email = recipientEmail }
            };

            // Configure arguments
            var args = new MutliRecipientArgs(
                _endpoint,
                _serial,
                _apiUser,
                _apiPassword,
                recipients,
                htmlBody,
                subject,
                password,
                filesList: null,
                SendMethodEnum.onlyEmail,
                sendByMyOwnSMTPServer: false,
                showSubject: true,
                getNotify: true,
                culture: "en-CA",
                maxOpeningTime: 5,        // Maximum 5 openings
                expirationMinutes: 1440   // 24 hours
            );

            // Send the message
            MultiRecipientAnswer response = MessageHelper.MultiRecipientMessage(args);

            // Check the result
            if (response.Status == 200)
            {
                var recipientAnswer = response.RecipientsAnswer[0].Answer;
                Console.WriteLine($"Message sent successfully!");
                Console.WriteLine($"URL: {recipientAnswer.URL}");
                Console.WriteLine($"Opening code: {recipientAnswer.DefaultOpeningCode}");
                return recipientAnswer.URL;
            }
            else
            {
                Console.WriteLine($"Error sending message: {response.Data}");
                Console.WriteLine($"Status code: {response.Status}");
                return null;
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Exception: {ex.Message}");
            return null;
        }
    }
}

// Usage
class Program
{
    static void Main(string[] args)
    {
        var service = new MessageService(
            SecureExchangesConfig.Serial,
            SecureExchangesConfig.ApiUser,
            SecureExchangesConfig.ApiPassword
        );

        string messageUrl = service.SendSecureMessage(
            "recipient@example.com",
            "Confidential Information",
            "<h1>Hello</h1><p>Here is your confidential document.</p>"
        );

        if (messageUrl != null)
        {
            Console.WriteLine($"Message accessible at: {messageUrl}");
        }
    }
}

Available Environments

Environment	Endpoint	Usage
Production	https://www.secure-exchanges.com/_api/0217/0217.asmx	Production applications
Preview	https://preview.secure-exchanges.com/_api/0217/0217.asmx	Testing and validation

Configuration for Preview Environment

// To use the test environment
Uri endpoint = new Uri("https://preview.secure-exchanges.com/_api/0217/0217.asmx");

// Additional configuration for Preview
SettingsHelper.CustomFileHandler = "https://preview.secure-exchanges.com/Handler/ReadFileTob64.ashx";
SettingsHelper.CustomSEMSEndpoint = "https://previewsems.secure-exchanges.com/SEMS_api.asmx";

Troubleshooting

Error 401 - Unauthorized

• Verify that your credentials are correct
• Ensure the API license is active
• Check that Serial, ApiUser, and ApiPassword match

Error 403 - Forbidden

• The license may have expired
• The account doesn't have required permissions
• Contact Secure Exchanges support

SSL Connection Error

• Verify that your system has up-to-date root certificates
• Ensure TLS 1.2 or higher is enabled
• Contact your network administrator if the issue persists

Next Steps

• SDK Architecture
• Sending Messages with Files
• Electronic Signatures
• Best Practices