The vCard standard allows for "extended" (aka non-standard) properties and parameters to exist in a vCard. They are called "extended" because they are not part of the vCard specification. Extended property and parameter names MUST start with X-. Many email clients make use of extended properties to store additional data.

1 Extended Properties

1.1 Retrieving

To retrieve extended properties from a VCard object, use the VCard.getExtendedProperties() method. This will return a list of RawProperty objects whose names match the name that was passed into the method.

The example below prints the values of all X-MS-MANAGER properties in a vCard.

VCard vcard = ...
List<RawProperty> managers = vcard.getExtendedProperties("X-MS-MANAGER");
for (RawProperty manager : managers){
  System.out.println("Manager: " + manager.getValue());
}

1.2 Adding

To add an extended property to a VCard object, call the VCard.addExtendedProperty() method. This method returns the RawProperty object that was added to the vCard, allowing you to make further modifications to the property if necessary.

The example below creates a X-SPOUSE property and assigns a group name to it.

VCard vcard = new VCard();
RawProperty spouse = vcard.addExtendedProperty("X-SPOUSE", "Jane Doe");
spouse.setGroup("item1");

Note that it's also possible to create custom property classes using a pluggable API. See the Property scribe page for more information.

2 Extended Parameters

2.1 Retrieving

To retrieve an extended parameter (or any parameter for that matter), call the getParameter() or getParameters() method on the property object.

The example below retrieves a parameter named X-GENDER from the FN property.

VCard vcard = ...
FormattedName fn = vcard.getFormattedName();
String gender = fn.getParameter("X-GENDER");

2.2 Adding

To add an extended parameter (or any parameter for that matter) to a property, call the addParameter() method.

The example below adds a parameter named X-GENDER to the FN property.

FormattedName fn = new FormattedName("John Doe");
fn.addParameter("X-GENDER", "male");