Client Developer Guide

From Direct Project
Jump to: navigation, search
Documentation and Testing Workgroup > Documentation Priorities > SMTP Client Developer's Guide> Draft 01


The SMTP Client Developer Guide enables SMTP Client Developer's Guide seeks to answer the following questions.
  1. What is the purpose of the NHIN Direct SMTP Client Library?
  2. How can a developer use the SMTP Client Library to:
    • Receive inbound messages from a HISP,
    • Construct an outbound message to a HISP


<tony: ensure that relevant fundementals are addressed here>


Describe the three different models>
a) HISP model: Agent is coupled with e-mail server (e.g., Exchange, Postfix, etc.), server stores decrypted mail messages, Client is configured with mutual TLS or server TLS + shared secret and uses normal e-mail retrieval (POP3/IMAP4)
b) HISP + organizational e-mail server: Agent+Gateway forwards to the "real SMTP server" via mutual TLS, "real SMTP server" makes email accessible to client.
c) HISP proxy: Agent speaks SMTP and IMAP4, sits in the firewall and encrypts/decrypts messages on the fly (we haven't built support for that yet, but it's a viable model).


Receive incoming Message from a HISP

An inbound SMTP message is received, decrypted, and the XDM contents are unpackaged into individual files

<Developer Resource... replace psuedo code with two example. One for C# and the other for Java>
and configure it Instantiate Listening Client

NhinDirectClient client= new NhinDirectClient ()

{ serverName =””,

UseMutualTLS = true,

PollTimeInSeconds= 60


Subscribe to the Event
client.MessageReceived +=ClientMessageReceived;

public void ClientMessageReceived(object sender, NHINDMessage message)

foreach (Document document in message.Attachments)

DocumentType docType = document.DocumentType; CCD, CCR, Lab Results, …
String docName = document.DocumentName; “PatientDischargeSummary”

byte[] rawBytes = document.Document; Here are the raw bytes, do as you would.

DoSomethingUseful(docType, docName, rawBytes);



Send outbound Message to a HISP

An outound SMTP message is encrypted, contents are packaged into an XDM, and addressed and submitted to a HISP

<Developer Resource... replace psuedo code with two example. One for C# and the other for Java
Taken from>
using Health.Net.Direct;

var sender = new Address("");
var receivers = from a
in ["", "", ""]
select new Address(a);

var message = new Message(sender, receivers);

message.TextMessage = File.ReadAllText("message.txt");

The following automatically extract metadata

Manual addition of metadata
var document = new Document();
document.Author = new Author("Arien", "Malec");

Metadata metadata = message.Metadata; allows for getting/setting metadata properties

XMLDocument xds_metadata = metadata.ToXDSMetadata();

XDMZip xdmzip = message.ToXDM();

string outgoing_email = message.ToRfc5322(); // RFC 5322 email message with Base64 encoded XDM attachment

var client_config = new ClientConfiguration("config.xml");

var client = new Client(client_config);


Best Practices

<October Code-A-Thon Team: Fill this out>