Email Addresses

  • Article

We've had a few forum questions lately on email addresses so I figured I would send out some clarifying info.

Most of you are aware that the Account and the Record are separate but related entities in HealthVault.  Each user account can have varying degrees of access to one or many records.  So when you start thinking "email" you have to wonder whether you want to email the account-holder or the record-holder.  The account-holder's email can be retrieved by an application by calling PersonInfo.GetSelfRecord() and then looking for the PersonalContactInfo singleton object.  The record-holder's email is in the record at PersonInfo.SelectedRecord.

You login to an account with a credential that is usually a LiveId but the email address / login name for this LiveId is not stored in HealthVault nor is it directly available via the HealthVault API.  This LiveId email address is often the same as the account-holder email in HealthVault but there is no guarantee that this will be the case.

When a user creates a record in the HealthVault UI, they must specify an email address.  If they just signed up for an account and this record is their Self record then the email address that they used at account sign-up may get copied into the input form but the user can change this.  After record creation, a user can change any record email address to which they have access by using the "Edit Profile" link in the HealthVault shell.

Once you have that email address, you can use your own server to send email or you can use the HealthVault API to do so.  If you elect to use the HealthVault API, note that you will need to make two config changes first, via https://config.healthvault-ppe.com:

  • Add the Send Email method group on the Method Mask tab
  • Specify the Email Domain from which your application's emails will originate.  You will set the sender address when calling our email-sending methods and the HealthVault platform will check that this sender address matches the domain on file. 

HealthVault provides a way for applications to email their end users without requiring access to PersonalContactInfo.  This is a privacy feature.  Regardless of whether this approach is used, an applications Terms of Use must make it clear to end users that the application may send them email.

SendInsecureMessageFromApplication has two signatures:

  • The first signature lets you specify a list of recipients by (DisplayName, EmailAddress). You can use this in the case where you know the recipient email addresses via any of the data types mentioned above.
  • The second signature lets you specify a list of recipients by PersonId.  You can use this in the case where you don't know the account-holder's email address but you still want to contact them.  This protects the user's privacy by never sharing their address.  This function leverages the email address in the PersonalContactInfo field of the first Self record of the user.

SendInsecureMessageToCustodiansFromApplication takes a RecordId as a parameter.  This method will send your note to every custodian of the record in question.

Note that all of these methods are called "SendInsecureMessage..." because email is not a secure protocol and you should not send health information through email.  (Consult a lawyer if this is unclear.)

Questions on any of this?  Please ask on the forum in order to get the quickest possible response.