Docmail

1 Docmail Online mail management system Web Service Help Version 15th June 2018. 2018 CFH Docmail Limited St Peters Park Wells Road Radstock BA3 3UP. Ownership & Confidentiality No part of this document may be disclosed orally or in writing, including by reproduction, to any third party without the prior written consent of CFH Docmail Limited. This document its associated appendices and any attachments remain the property of CFH Docmail Limited and shall be returned upon request. Docmail Web Service Version 2. 5. Referencing the web service .. 6. Set up a Docmail account to use the web service .. 6. Details of the service .. 8. Data formats .. 9. Return Formats .. 9. Template File 10. Mailing List File 10. 1 - Creating Mailings .. 11. Create File Mailing .. 11. Create Mailing.

2 12. Add Mailing Filter .. 14. Add Delivery Address .. 15. Update Mailing Options .. 16. 2 - Mail Packs .. 17. Add Template File .. 17. Add Template Background File .. 18. Add Template From Library .. 19. Add Template From 20. Add Mail Pack From Library .. 20. Add Mail Pack From Order .. 21. Add Designer Template .. 22. Add Designer Image .. 23. Add Designer Stored Image .. 23. Add Designer Text .. 24. Set Mail Pack Variable Value .. 25. Set Template Variable Value .. 25. Get Template Image .. 26. Data 27. Add Template Use Rule .. 28. Add Template Background Rule .. 29. 3 - Mailing Lists .. 30. Add Mailing List File .. 30. Add Mailing List String .. 31. Docmail Web Service 2018 CFH Docmail Ltd Page 2. Add Mailing List From Library .. 32. Add Mailing List From 32. Add Address.

3 33. Add Self .. 34. Auto Correct Addresses .. 35. Set Mailing List Proof Option .. 35. 4 - Delete and Cancel .. 36. Delete Template .. 36. Delete Mail Pack .. 36. Delete Mailing List .. 37. Delete 37. Cancel Mailing .. 37. 5 - 38. Process Mailing .. 38. Get Mailing Details .. 40. Get Status .. 43. Get Proof File .. 44. Get Proof Image .. 44. Get 45. Get Mailing GUID From Order Ref .. 45. User Approve Mailing .. 46. Cancel Mailing Approval .. 46. 6 - Lists .. 47. List 47. List 47. List Mailings Page Count .. 49. List Library Templates .. 50. List Library Templates Page Count .. 51. List Library Backgrounds .. 52. List Library Backgrounds Page Count .. 53. List Library Mail 54. List Library Mail Packs Page Count .. 55. List Library Mailing Lists .. 56. List Library Mailing Lists Page Count.

4 56. List Mailing Filter Categories .. 56. Docmail Web Service 2018 CFH Docmail Ltd Page 3. List Mailing Filters For Category .. 57. List Mailing Variable Values .. 57. List Product Types .. 58. List Document Types .. 58. List Template Variables .. 59. 7 - Zip Data .. 60. Get Mail Pack Zip .. 60. Get Mailing List Zip .. 60. 8 - Account and User Administration .. 61. Create 61. Add User .. 62. Add User Organisation Structure Link .. 63. Add User Sign-up Data .. 63. 9 - Mailing List Address Counts and Price Estimates .. 64. Add Mailing List File For Address Count .. 64. Add Mailing List String For Address Count .. 65. Poll Mailing List For Address Count .. 66. Get Mailing Price Estimate .. 67. Get Price Estimate .. 68. 10 - Adding Library Data .. 69. Add Mailing List File To Library.

5 69. Add Mailing List String To 69. Add Template File To Library .. 70. Add Background File To Library .. 71. Add Mail Pack To Library .. 72. Add Template To Library Mail Pack .. 72. 11 - Extended Calls .. 73. Extended Call .. 73. Extended Call Definition .. 74. Extended Call Methods .. 74. Error codes .. 94. Example code .. 96. Adding a service reference or web reference in .NET .. 96. Service Reference configuration .. 96. VB .NET Code Samples .. 97. Glossary of terms and system limits .. 100. Docmail Web Service 2018 CFH Docmail Ltd Page 4. Overview The following help is for the Docmail web service version The previous version web service and simple API are still supported, but we recommend that version is used for all new development. If you are not familiar with the Docmail system then please refer to the Glossary of terms at the back of the help guide, or read the Docmail help guide on the website to familiarise yourselves with Docmail terminology.

6 The following best practice should be considered when designing an application to call the Docmail API: Try to minimise the data traffic you send to the Docmail API by: a. Using a library template or mail pack rather than submitting the same document on every mailing. b. Using the Create File Mailing call so all data is packaged within a single zip file, please see the DocmailZip open source .NET DLL available via the API. web page c. If you application does not require waiting for completion then consider using the HTTP post options in the Process Mailing call rather than polling for completion. Do: Create as few mailings as possible, using data intelligence or multiple address stream documents where required. Create mailings as required or create a central queue at a single location to submit mailings in one go.

7 Use library documents or mail packs where possible to avoid sending file data with every call. Supply data in a compressed zip files where possible. Use temporary pass keys to avoid sending the password in every call. Monitor mailing progress with call back URLs. Trap for errors on all API calls and consider the process required to cancel or re-try failures. Supply a customer application that identifies the source system, this can include a version number from your system. Don't: Create a mailing for every item. Send items from multiple sites at the same time of day. Supply the username and password when making multiple calls. Poll for status updates without a reasonable wait times between each call. Ignore errors, as mailings may not be sent. Leave the customer application blank or supply a customer application that cannot identify the source system.

8 Docmail Web Service 2018 CFH Docmail Ltd Page 5. Referencing the web service The Docmail API is a SOAP-based web service and in order to connect you will need the WSDL (service description) page URL, these can be found at: For testing: The testing API has an associated test website, please use this website to set-up a test account: Note: Please reference the live XML schemas when using the test API. For live: For live API use the main Docmail website, please use this website to set-up a live account: Set up a Docmail account to use the web service Using the Docmail website (see the Docmail Web Service 2018 CFH Docmail Ltd Page 6. Referencing the web service section above for the relevant URL) either create an account or login to an existing account. During the sign-up process you can select whether the main account user can access the web service, this option can be changed at any time in the website from the Admin My Login Details screen.

9 To add an additional user for web service access, go to Admin Additional users and click the Add new user link. Enter a login name and password for the web service user, ensuring that the Can use web service is checked, along with the other required permissions. Note: In order to use the SendToSelf option when placing a mailing you must login to the Docmail website with the new user and enter the address details. Docmail Web Service 2018 CFH Docmail Ltd Page 7. Details of the service The operations available from the web service will be referenced under the following sections to help guide you through the order of use when creating a mailing and then to look at additional advanced calls available: 1 - Creating Mailing 2 - Mail Packs 3 - Mailing Lists 4 - Delete and Cancel 5 - Payment 6 - Lists 7 - Zip Data 8 - Account and User Administration 9 - Mailing List Address Counts and Price Estimates 10 - Adding Library Data 11 - Extended Calls All calls will return data as either a string or a byte array.

10 If failure is returned from a call that returns a byte array, then a UTF 8 encoded failure string of one of the Return Formats will be returned. If the call has no return value specified then a successful call will include a Success . flag with the value True; otherwise a successful call will return the data specified. Docmail Web Service 2018 CFH Docmail Ltd Page 8. Data formats Return Formats Text (default if return format is not specified). The return string is in the format of a new line for each item, with the header followed by a colon and a space then the data. Example result text data: MailingGUID: 00000000-0000-0000-0000-000000000000. XML. The return string will be formatted in XML. The definition for the XML result can be found at Example result XML data: <?xml version=" " encoding="utf-8" ?