Message Polling with Address Groups

Use of Address Groups is required for production accounts because authentication at the Address level for production message or notification polling is only permitted within OpenEMR integrations. Address Groups allow a software integration to connect at the organization level or EHR level (depending on the deployment model) and poll for any new incoming messages and status notifications with a single connection to phiMail server (EHR level) or one connection per organization (Organization/practice level).

Message polling is accomplished differently depending on your deployment model:
1. At the Organization level if phiMail is deployed for multiple organizations in instances that are not each entirely secured by the integrator. The Organization level Address Group credential can retrieve or send messages for any Direct address in that organization's group.
2. Using an Address Group at the EHR level if deployed to multiple organizations and centrally-hosted and secured by the integrator, or when phiMail is deployed by the integrator to a single organization only. The EHR level Address Group credential can retrieve or send messages for any Direct address in that group.

When authenticated to phiMail server as the Address Group username, calls to check() will return the next available message or status notification for any addresses in the corresponding group, so you can efficiently check all relevant mailboxes without iterating through addresses.

If authentication is enabled at the EHR level, the Address Group username will be assigned by EMR Direct and is sent to you via Direct message along with your production client authentication certificate.

If authentication is enabled at the Organization level, the Address Group username is the Direct subdomain starting with @, as chosen by the account's organizational representative.

It is recommended that your background polling process connect and authenticate using your address group as the username at least once every half hour to retrieve new messages and notifications. Please note that connecting less frequently than once every half hour to poll for and acknowledge messages can result in senders marking messages that they send to your customers as failures if they request confirmation of final delivery within a fixed timeout period (usually one hour). Please see the CHECK section of the phiMail API documentation for further details.

For message sending, applications always authenticate as the Direct Address, which inherits the authentication assigned to the relevant Address Group.

Did this article answer your question? If not, please contact us.