Know How: associate accounts to newsletters


This example proposes inscribe a person, based to its email, to a newsletter.


Subscription to a newsletter is usually handled through a contact criterion. If the institution manages many newsletters (for example, newsletters for specific topics), it’ll use so many criteria.

If we want to register a contact and subscribe him to a newsletter, we’ll have to:

  • Search if a contact already exists with the given email.
    • If No : create it, and set its authorisation to receive emails from the organization to true.
    • If yes, retrieve its contactNumber
  • Then update the contact criterion corresponding to the newsletter (many criteria can be updated at once, if necessary)

Demo method

private void demo() {
    // Initializing the service.
    ContactInformationPublicService service = initService();

    // Generate a sample email, for demonstration purpose.
    String generatedEmail = "example.person" + System.currentTimeMillis() + "";

    // Here put the contact criterion id code for your newsletter.
    String criterionCode = "NEWSLET";
    boolean contactSubscribesToNewsletter = true;

    // Here is the code of the authorization that checks if a person accepts to receive emails or not.
    // This code is most the of the time this one.
    String authorizationCode = "CNIL_O";
    boolean contactAcceptsToReceiveEmails = true;

    // Those two calls are not necessary every time, but they guarantee that we are using real and available
    // authorization and criterion codes.
    Assert.isTrue(checkThatAuthorizationCodeExists(service, authorizationCode));
    Assert.isTrue(checkThatCriterionCodeExists(service, criterionCode));

    registerToNewsletter(service, generatedEmail, criterionCode, contactSubscribesToNewsletter, authorizationCode, contactAcceptsToReceiveEmails);

Subscribing to newsletter

protected void registerToNewsletter(ContactInformationPublicService service, String contactEmail, String criterionCode,
    boolean contactSubscribesToNewsletter, String authorizationCode, boolean contactAcceptsToReceiveEmails) {

    // Searches if a contact with the given email is already registered in the database.
    ContactTextSearch searchCriteria = new ContactTextSearch();
    ContactSearchResult searchResult =
        service.searchContactByCriteria(null, null, null, null, null, null, searchCriteria, null, true, 0l, 1l);

    final String contactNumber;
    final IndividualContactData individualContactData;
    final List<AuthorizationData> listOfAuthorizationsToUpdate;
    if (searchResult.getContacts() != null && searchResult.getContacts().size() > 0) {
        // A contact with the given email already exists !
        contactNumber = searchResult.getContacts().get(0).getContactNumber();
        individualContactData = null;
        listOfAuthorizationsToUpdate = null; // If the contact already exists, we do not update its authorizations.
    } else {
        // The contact has to be created. We fill the minimal values.
        contactNumber = null;
        individualContactData = new IndividualContactData();
        // Here we set the authorization.
        AuthorizationData authorization = new AuthorizationData();
        listOfAuthorizationsToUpdate = Collections.singletonList(authorization);

    Assert.isTrue(contactNumber != null || individualContactData != null);

    // Here we set the criterion (inscription to newsletter)
    ExternalContactCriterionData criterion = new ExternalContactCriterionData();
    criterion.setValues(Collections.singletonList("" + contactSubscribesToNewsletter));

    // Contact is created (if necessary), and authorization and criterion are set.

    ContactDataResult saveIndividualResult =
      service.saveIndividualContactData(contactNumber, individualContactData, null, false,
        listOfAuthorizationsToUpdate, false, Collections.singletonList(criterion), false, null, false, null);


Checking authorization and criterion

Warning : those methods must NOT be called everytime. They are here to demonstrate how, in development process, it is possible to check the existence of a criterion or an authorization code.

protected boolean checkThatCriterionCodeExists(ContactInformationPublicService service, String criterionCode) {
    ExternalContactCriterionResult availableCriteriaResult = service.getAvailableContactCriteria();

    boolean criteriaCodeExists = false;
    for (ExternalContactCriterionDefinitionData criterionData : availableCriteriaResult
        .getContactCriterionDefinitionDatas()) {
        if (criterionData.getCriterionIdCode().equals(criterionCode)) {
            criteriaCodeExists = true;
    return criteriaCodeExists;

protected boolean checkThatAuthorizationCodeExists(ContactInformationPublicService service, String authorizationCode) {
    AvailableAuthorizationsResult availableAuthorizationResult = service.getAvailableAuthorizations();

    boolean authorizationExists = false;
    for (AuthorizationDefinitionData authorizationData : availableAuthorizationResult
        .getAuthorizationDefinitionData()) {
        if (authorizationData.getAuthorizationCode().equals(authorizationCode)) {
          authorizationExists = true;
    return authorizationExists;