How to use

Bulkmail webservice

You must go through a number of phases to be able to use the BulkMail web service. This site describes the procedure, the requirements and the instructions. 

If you want to make use of the BulkMail web service, please contact the MijnPost team or send a mail to supportb2b@postnl.nl. It is not possible to request access to this web service via this website. 

Procedure

PostNL will ask you under which (primary) customer number you want to use the BulkMail web service and under which customer number(s) you want to be able to give advance notification and present shipments. A B2B account will be created for you in the BulkMail web service test environment. This will allow you to test the link; (the account receives an recognisable name so that it is clear in MijnPost that shipments are created by a B2B account). 

The UPN and the primary customer number of the B2B account are included in the certificate which must be created and issued to the customer in order to be able to test in the PostNL test environment. 

The following information will be communicated to you: 

  • the certificate;
  • the B2B account;
  • the WSDL link;
  • the BulkMail web service user guide.
You can then test using the BulkMail web service. Verification of the valid delivery of shipments and advance notifications via the BulkMail web service test environment will be conducted by PostNL. If the tests go well, the same steps will be followed for putting into production your connection to the BulkMail web service: 
  • PostNL will ask you under which (primary) customer number you want to use the BulkMail web service and under which customer number(s) you want to be able to give advance notification and present shipments.
  • A B2B account will be created for you in the production environment of MijnPost. This will allow you to use the link; (the account is given a recognisable name so that it is clear in MijnPost that shipments have been created by a B2B account). 
  • The UPN and the primary customer number of the B2B account are included in the certificate, which must be created and issued to the customer in order to be able to use the MyBulkMail web service for production. 
  • PostNL will check which B2B variables (customer numbers, product numbers, contract numbers, and ORIKs - OrderRegel Identificatie Kenmerken) you can use. 
You can then use the BulkMail web service in production. 

Required test environment

Onderstaande gegevens zijn nodig om de webservice op de testomgeving aan te roepen en eventueel de orders in MijnPost op te vragen.

Description

Explanation

Certificate

The certificate is a “pfx” file: “xxx.pfx”; these will be communicated via mail

WSDL of the test environment (a/pat environment)

https://bp-b2bservice.mijnpost.pat.postnl.nl/B2BService.svc

URL B2B web service

https://bp-b2bservice.mijnpost.pat.postnl.nl/B2BService.svc

URL of the MijnPost test environment (a/pat environment)

https://uat-mijnpostnl.cs101.force.com/

Login account and password for MijnPost

these will be communicated via mail

When you and PostNL agree that your organisation can connect to the BulkMail web service, you will receive the following: 

  • a user guide for the BulkMail web service; 
  • the WSDL; the URL of the web service in our test environment will be:https://b2b-2.mijnpost.pat.postnl.nl/B2BService.svc. The WSDL can only be collected if you have a valid certificate; 
  • a certificate;
  • an account which is linked to MijnPost, your customer number and the certificate; 

Additional requirements to be able to connect to the BulkMail web service: 
  • You will have to adjust your own software (at your own expense) so that you can provide the XML messages in accordance with PostNL’s specifications; 
  • A tool to be able to open the presentation form which you receive in a response message, for example: ‘ByteArrayToPdf’. 

Message types

PreAdviceBulkMailOrder

Give advance notification of a shipment

ValidateAdressAttachment

Verify an address file

GetValdiationResult

Download files for unsorted products

ValidateAndSortAddressAttachment

Sort an address file

GetValidationAndSortingResult

Download files for sorted products

GetPackagingInformation

Download PackagingCards

TenderBulkMailOrder

Present a shipment

These messages, which are used in the BulkMail web service, are described in the Message Implementation Guides (MIGs): 

  • “MIG – AddressAttachement”
  • "MIG – Bulkmailorder” 
  • “MIG – PackagingInformation”

See documentation tab

Example of presenting shipments

Below are a few examples of products you can offer and the order of messages associated with them.

Product 101 (Registered mail) does not need to be verified or sorted:
Step 1 – PreAdviceBulkMailOrderV2 (= Advance notification)
Stap 2 – TenderBulkMailOrderV2 (= Present)

Product 2821 (24 hr Mixed):
Step 1 – PreAdviceBulkMailOrderV2 (= Advance notification)
Step 2 – ValidateAddressAttachmentV1 (Verify an address file)
Step 3 – GetValidationResultV1 (Download files)
Step 4 – TenderBulkMailOrderV2 (= Present)

Product 2835 (Basic Special, sorted):
Step 1 – PreAdviceBulkMailOrderV2 (= Advance notification)
Step 2 – ValidateAndSortAddressAttachmentV1 (Sort an address file)
Step 3 – GetValidationAndSortingResultV1 (Download files)
Step 4 – TenderBulkMailOrderV2 (= Present)

Instructions

For example, present shipment of Product 2835 (Basic Special, sorted): Step 1 – PreAdviceBulkMailOrderV2 (= Advance notification)
Step 2 – ValidateAndSortAddressAttachmentV1 (Sort an address file)
Step 3 – GetValidationAndSortingResultV1 (Download files)
Step 4 – TenderBulkMailOrderV2 (= Present)

Using Product 2835, below is an explanation of how to go through the steps using the messages.
Step 1 – Give advance notification of a shipment with Product 2835 Basic Special, sorted.
Create a message with PreAdviceBulkMailOrderV2.
Make sure you have a valid date in element ConsignmentShippingDate and give the shipment a recognisable description.
You do this in the following element ORIK-1 (= description of the shipment).

<b:DocumentID> <b:ID> <b:Value>d29fc733-367f-4e7d-b1bc-c4764c6542d8</b:Value> <b:schemeAgencyID i:nil="true"/> <b:schemeAgencySchemeAgencyID i:nil="true"/> <b:schemeAgencySchemeID i:nil="true"/> <b:schemeID i:nil="true"/> <b:schemeVersionID i:nil="true"/> </b:ID> <b:RevisionID i:nil="true"/> <b:VariationID i:nil="true"/> <b:agencyRole i:nil="true"/> </b:DocumentID>

Step 2 – From the response message (= PreAdviceBulkMailOrderV2Response) of Step 1 you must copy the element Consignmentid 100016843407 (example).

Step 3 – Go to the message ValidateAndSortAddressAttachmentV1 and copy the Consignmentid 100016843407 as Value for the element Consignmentid.
If you are sure you have correctly entered all Values, click again on the green triangle. The address file is now being sorted.

Step 4 – Now go to the message GetValidationAndSortingResultV1, which you will use to download the files. Once again, fill in the ConsignmentId 100016843407 in this message and, from the response message (= ValidateAndSortAddressAttachmentV1Response) of Step 3, copy the Value found at the string of element DocumentID (see the boldfaced part below).

Step 2 – From the response message (= PreAdviceBulkMailOrderV2Response) of Step 1 you must copy the element Consignmentid 100016843407 (example).

Step 3 – Go to the message ValidateAndSortAddressAttachmentV1 and copy the Consignmentid 100016843407 as Value for the element Consignmentid.
If you are sure you have correctly entered all Values, click again on the green triangle. The address file is now being sorted.

Step 4 – Now go to the message GetValidationAndSortingResultV1, which you will use to download the files. Once again, fill in the ConsignmentId 100016843407 in this message and, from the response message (= ValidateAndSortAddressAttachmentV1Response) of Step 3, copy the Value found at the string of element DocumentID (see the boldfaced part below).

<b:DocumentID> <b:ID> <b:Value>d29fc733-367f-4e7d-b1bc-c4764c6542d8</b:Value> <b:schemeAgencyID i:nil="true"/> <b:schemeAgencySchemeAgencyID i:nil="true"/> <b:schemeAgencySchemeID i:nil="true"/> <b:schemeID i:nil="true"/> <b:schemeVersionID i:nil="true"/> </b:ID> <b:RevisionID i:nil="true"/> <b:VariationID i:nil="true"/> <b:agencyRole i:nil="true"/> </b:DocumentID>

This string (only the boldfaced part above) must be pasted as a Value at the element DocumentID (see screen print below), and again click on the green triangle. 

Instructies Bulkmail webservice, screenprint1

Step 5 – When the response message (GetValidationAndSortingResultV1Response) of Step 4 is ready, you must copy the string which is at the element EmbeddedData. 

Instructies Bulkmail webservice, screenprint2

Questions during testing

Questions about the B2B web service during the test phase can be posed to the Mijn PostNL team by sending an e-mail to supportb2b@postnl.nl.