Send Your First Message

This guide shows you how to send a secure message with the SDK.

Basic Concepts

A Secure Exchanges message includes:

  • Recipient(s): Email and/or phone
  • Subject: Message title
  • Body: HTML or text content
  • Options: Expiration, notifications, password

Quick Example

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

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

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

var args = new MutliRecipientArgs(
    endpoint, serial, apiUser, apiPassword,
    recipients,
    "My message content",
    "My subject",
    password: null,
    filesList: null,
    SendMethodEnum.onlyEmail,
    false, true, true, "en-CA", 5, 1440
);

var response = MessageHelper.MultiRecipientMessage(args);

if (response.Status == 200)
{
    Console.WriteLine($"URL: {response.RecipientsAnswer[0].Answer.URL}");
}

Complete Example with Context

Scenario: Sending Temporary Passwords

A company needs to send temporary passwords to clients securely.

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 PasswordDeliveryService
{
    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 PasswordDeliveryService(Guid serial, Guid apiUser, Guid apiPassword)
    {
        _serial = serial;
        _apiUser = apiUser;
        _apiPassword = apiPassword;
        _endpoint = DefaultEndpoint;
    }

    /// <summary>
    /// Sends a temporary password securely
    /// </summary>
    public PasswordDeliveryResult SendTemporaryPassword(
        string clientEmail,
        string clientName,
        string temporaryPassword,
        int expirationHours = 24)
    {
        // Build HTML message
        string htmlBody = $@"
            <div style='font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto;'>
                <h2>Hello {clientName},</h2>
                <p>Here is your temporary password:</p>
                <div style='background-color: #f5f5f5; padding: 20px; border-radius: 5px; margin: 20px 0;'>
                    <code style='font-size: 18px; font-weight: bold;'>{temporaryPassword}</code>
                </div>
                <p><strong>Important:</strong></p>
                <ul>
                    <li>This password expires in {expirationHours} hours</li>
                    <li>Change it after your first login</li>
                    <li>Never share this password</li>
                </ul>
                <p>Best regards,<br/>The Support Team</p>
            </div>";

        // Configure recipients
        var recipients = new List<RecipientInfo>
        {
            new RecipientInfo { Email = clientEmail }
        };

        // Configure arguments
        var args = new MutliRecipientArgs(
            _endpoint,
            _serial,
            _apiUser,
            _apiPassword,
            recipients,
            htmlBody,
            subject: "Your Temporary Password",
            password: null,  // No additional password
            filesList: null,
            SendMethodEnum.onlyEmail,
            sendByMyOwnSMTPServer: false,
            showSubject: true,
            getNotify: true,  // Receive notification on opening
            culture: "en-CA",
            maxOpeningTime: 3,  // Maximum 3 openings
            expirationMinutes: expirationHours * 60
        );

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

        // Process response
        if (response.Status == 200)
        {
            var answer = response.RecipientsAnswer[0].Answer;
            return new PasswordDeliveryResult
            {
                Success = true,
                MessageUrl = answer.URL,
                OpeningCode = answer.DefaultOpeningCode,
                TrackingId = ExtractTrackingId(answer.URL)
            };
        }
        else
        {
            return new PasswordDeliveryResult
            {
                Success = false,
                ErrorMessage = response.Data,
                ErrorCode = response.Status
            };
        }
    }

    private string ExtractTrackingId(string url)
    {
        // Extract tracking ID from URL
        var uri = new Uri(url);
        var query = System.Web.HttpUtility.ParseQueryString(uri.Query);
        return query["Sess"];
    }
}

public class PasswordDeliveryResult
{
    public bool Success { get; set; }
    public string MessageUrl { get; set; }
    public string OpeningCode { get; set; }
    public string TrackingId { get; set; }
    public string ErrorMessage { get; set; }
    public int ErrorCode { get; set; }
}

// Usage
class Program
{
    static void Main()
    {
        var service = new PasswordDeliveryService(serial, apiUser, apiPassword);

        var result = service.SendTemporaryPassword(
            clientEmail: "client@example.com",
            clientName: "John Doe",
            temporaryPassword: "TempPass123!",
            expirationHours: 24
        );

        if (result.Success)
        {
            Console.WriteLine($"Password sent!");
            Console.WriteLine($"URL: {result.MessageUrl}");
            Console.WriteLine($"Tracking: {result.TrackingId}");
        }
        else
        {
            Console.WriteLine($"Error {result.ErrorCode}: {result.ErrorMessage}");
        }
    }
}

Available Send Methods

Method Description
onlyEmail Email only
onlySMS SMS only
msgEmailCodeSMS Message via email, code via SMS
msgSMSCodeEmail Message via SMS, code via email

Example with Two-Factor Authentication (Email + SMS)

// Recipient must have both email AND phone
var recipients = new List<RecipientInfo>
{
    new RecipientInfo
    {
        Email = "client@example.com",
        Phone = "+1234567890"  // International format
    }
};

var args = new MutliRecipientArgs(
    endpoint, serial, apiUser, apiPassword,
    recipients,
    "Confidential message",
    "Subject",
    password: null,
    filesList: null,
    SendMethodEnum.msgEmailCodeSMS,  // Message via email, code via SMS
    false, true, true, "en-CA", 5, 1440
);

Configuration Options

Password Protection

var args = new MutliRecipientArgs(
    // ... other parameters ...
    password: "SecretPassword123"  // Recipient must enter this password
);

Opening Notification

var args = new MutliRecipientArgs(
    // ... other parameters ...
    getNotify: true  // You'll receive an email when message is opened
);

Expiration and Opening Limits

var args = new MutliRecipientArgs(
    // ... other parameters ...
    maxOpeningTime: 5,        // Maximum 5 openings
    expirationMinutes: 43200  // 30 days maximum
);

Error Handling

var response = MessageHelper.MultiRecipientMessage(args);

switch (response.Status)
{
    case 200:
        Console.WriteLine("Success!");
        break;
    case 400:
        Console.WriteLine($"Invalid parameters: {response.Data}");
        break;
    case 401:
        Console.WriteLine("Invalid API credentials");
        break;
    case 403:
        Console.WriteLine("Invalid or expired license");
        break;
    default:
        Console.WriteLine($"Error {response.Status}: {response.Data}");
        break;
}

See Also