Poll[Link]

Purpose

Allow registrars to pick up messages from the EPP server asynchronously.

The EPP Poll command is described in RFC4930. The EPP Poll command allows registrars to pick up and to discover and retrieve service messages queued by the EPP server for registrars.

The registrar must enable EPP messages before he can start using EPP Poll. This can be done via the registrar website. If the registrar disables EPP Poll, CPS e-mails are sent immediately when an action occurs.

When registrars update their profile to enable EPP Poll, all system-generated notifications will be kept in a queue. When the queue is non-empty, an EPP poll request will always retrieve the oldest message in the queue. After successfully retrieving the first message on the queue, the registrar must acknowledge the message to remove it from the queue and be able to receive the next message.

After a successful <poll> request with op=”req” from the registrar, the DNS Belgium server will send a reply containing a message counter, a server-unique message identifier and the first message from the queue. In case the message queue is empty, the server will reply that there are no messages pending.

Each message sent from the DNS Belgium server must be acknowledged by the registrar by sending an “ack” request containing the server-unique ID of the message that is being acknowledged.

After receiving the acknowledgement from the registrar, the DNS Belgium server will send a reply confirming the registrar’s acknowledgement and indicating the new number of messages in the queue.

This method can be used to iterate through all pending messages.

The system makes sure that all messages can only be acknowledged once, regardless of the chosen channel.

Note

  • Please be advised that unacknowledged poll messages are deleted after 1 year.

  • DNS Belgium recommends to retreive poll messages at least twice a day.

Rate limits are used for EPP poll: the registrar can do 60 <poll> requests per minute/IP. However, an exception has been made for acknowledging messages. Whenever a message is successfully acknowledged, the quota for <poll> requests is reset. This allows for a fast, automatic retrieval and processing of messages without abusing the system.

The poll command is composed according to the standard EPP syntax. Some components need further explanation:

  • <poll op=”req”/> Is the command tag to request the first message from the queue.

  • <poll op =”ack” msgID=”ID”> is the command tag to acknowledge a message from the registration system. “ID” should contain the value of the “id” attribute in the message that is being acknowledged.

Please refer to the examples to see a complete request.

Examples[Link]

A <poll> request for messages looks like:

<?xml version="1.0" encoding="UTF-8"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
  <command>
    <poll op="req"/>
    <clTRID>ABC-12345</clTRID>
  </command>
</epp>

When the registrar has no new messages, the server replies with:

<?xml version="1.0" encoding="UTF-8"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
  <response>
    <result code="1300">
      <msg>Command completed successfully; no messages</msg>
    </result>
    <trID>
      <clTRID>ABC-12345</clTRID>
      <svTRID>dnsbe-0</svTRID>
    </trID>
  </response>
</epp>

When the registrar has some messages, the server replies with:

<?xml version="1.0" encoding="UTF-8"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"       
     xmlns:dnsbe="http://www.dns.be/xml/epp/dnsbe-1.0">
  <response>
    <result code="1301">
      <msg>Command completed successfully; ack to dequeue</msg>  
    </result>  
    <msgQ count="3" id="441">
      <qDate>2011-09-07T09:44:43.014Z</qDate>
      <msg>Contact is now being monitored</msg>
    </msgQ>    
    <resData>
      <dnsbe:pollRes>
        <dnsbe:action>READY</dnsbe:action>
        <dnsbe:contact>c100000</dnsbe:contact>
        <dnsbe:date>2011-09-07T09:44:43.000Z</dnsbe:date>
        <dnsbe:returncode>1501</dnsbe:returncode>
        <dnsbe:type>MONITORED_UPD_CONTACT</dnsbe:type>
      </dnsbe:pollRes>
    </resData>
    <trID>
      <clTRID>ABC-12345</clTRID>
      <svTRID>dnsbe-0</svTRID>
    </trID>
  </response>
</epp>

The reply will always contain the following information:

  • <msgQ count> Contains the number of messages waiting in the queue and the unique identifier (id) of the message that is returned in this response. In this example, we see there are 3 messages in the queue and the id of the message included in this response is 441.

  • <qDate> contains the date and time the message was queued in UTC time.

  • <dnsbe:action> contains the action done for this particular contact or domain. All possible actions can be found here.

  • <dnsbe:returncode> contains the return code for this particular contact or domain. All possible return codes can be found here.

  • <dnsbe:type> contains the transaction type concerned. All possible types can be found here.

Depending on the purpose of message, the reply might also contain:

  • <dnsbe:contact> is the contact concerned in the message.

  • <dnsbe:domainname> is the domain name concerned in the message.

  • <dnsbe:date> is the relevant date in UTC time.

  • <dnsbe:email> is the relevant e-mail address.

  • <dnsbe:level> is the relevant watermark level.

  • <dnsbe:detailedcode> is the detailed code for the error in the bounced email.

  • <dnsbe:id> is the relevant id in the Registration System, this is used for the nsgroup name.

The server will keep returning the same message until it has been acknowledged:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
  <command>
    <poll op="ack" msgID="12345"/>
    <clTRID>ABC-12346</clTRID>
  </command>
</epp>

After receiving an acknowledgement, the server replies with:

<?xml version="1.0" encoding="UTF-8"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
  <response>
    <result code="1000">
      <msg>Command completed successfully</msg>
    </result>
    <msgQ count="2" id="149"/>
    <trID>
      <clTRID>ABC-12346</clTRID>
      <svTRID>dnsbe-0</svTRID>
    </trID>
  </response>
</epp>

Indicating there are more messages in the queue. Once the last message has been acknowledged, the server will reply with:

<?xml version="1.0" encoding="UTF-8"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
  <response>
    <result code="1300">
      <msg>Command completed successfully; no messages</msg>
    </result>
    <trID>
      <clTRID>ABC-12346</clTRID>
      <svTRID>dnsbe-0</svTRID>
    </trID>
  </response>
</epp>

When a registrar acknowledges a message again, or when he acknowledges the wrong message, the server replies with:

<?xml version="1.0" encoding="UTF-8"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:dnsbe="http://www.dns.be/xml/epp/dnsbe-1.0">
  <response>
    <result code="2002">
      <msg>Command use error</msg>
    </result>
    <extension>
      <dnsbe:ext>
        <dnsbe:result>
         <dnsbe:msg>No poll acknowledgement expected for the specified id</dnsbe:msg>
        </dnsbe:result>
      </dnsbe:ext>
    </extension>
    <trID>
      <clTRID>ABC-12346</clTRID>
      <svTRID>dnsbe-0</svTRID>
    </trID>
  </response>
</epp>

If the registrar didn’t enable EPP poll in his notification profile, the server will reply with:

<?xml version="1.0" encoding="UTF-8"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:dnsbe="http://www.dns.be/xml/epp/dnsbe-1.0">
  <response>
    <result code="2201">
      <msg>Authorization error</msg>
    </result>
    <extension>
      <dnsbe:ext>
        <dnsbe:result>
          <dnsbe:msg>Authorization error</dnsbe:msg>
        </dnsbe:result>
      </dnsbe:ext>
    </extension>
    <trID>
      <clTRID>ABC-12346</clTRID>
      <svTRID>dnsbe-0</svTRID>
    </trID>
  </response>
</epp>

When the registrar exceeds the quota for the poll request, the server replies with:

<?xml version="1.0" encoding="UTF-8"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:dnsbe="http://www.dns.be/xml/epp/dnsbe-1.0">
  <response>
    <result code="2306">
      <msg>Parameter value policy error</msg>
    </result>
    <extension>
      <dnsbe:ext>
        <dnsbe:result>
          <dnsbe:msg>Excessive querying</dnsbe:msg>
        </dnsbe:result>
      </dnsbe:ext>
    </extension>
    <trID>
      <clTRID>ABC-12345</clTRID>
      <svTRID>dnsbe-0</svTRID>
    </trID>
  </response>
</epp>

A poll request with op=”req” and a msgID will return a syntax error:

<?xml version="1.0" encoding="UTF-8"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:dnsbe="http://www.dns.be/xml/epp/dnsbe-1.0">
  <response>
    <result code="2001">
      <msg>Command syntax error</msg>
    </result>
    <extension>
      <dnsbe:ext>
        <dnsbe:result>
          <dnsbe:msg>no msgID allowed when op=req</dnsbe:msg>
        </dnsbe:result>
      </dnsbe:ext>
    </extension>
    <trID>
      <clTRID>ABC-12345</clTRID>
      <svTRID>dnsbe-0</svTRID>
    </trID>
  </response>
</epp>