Docmail

Online mail management system

Web Service Help

Version 2.0
22nd March 2011

© 2011 CFH Total Document Management 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 Total
Document Management Limited. This document its associated appendices and
any attachments remain the property of CFH Total Document Management Limited
and shall be returned upon request.
 Docmail Web Service Version 2

Overview..................................................................................................................... 5
Referencing the web service ............................................................................... 5
Set up a Docmail account to use the web service ............................................... 5
Details of the service .................................................................................................. 6
Data formats ........................................................................................................... 7
Return Formats.................................................................................................... 7
Template File Formats ......................................................................................... 7
Mailing List File Formats ...................................................................................... 7
1 - Creating Mailings ............................................................................................... 8
Create File Mailing............................................................................................... 8
Create Mailing ..................................................................................................... 9
Add Mailing Filter ............................................................................................... 10
Add Delivery Address ........................................................................................ 10
Update Mailing Options ..................................................................................... 11
2 - Mail Packs ....................................................................................................... 12
Add Template File ............................................................................................. 12
Add Template Background File ......................................................................... 13
Add Template From Library ............................................................................... 14
Add Template From Order ................................................................................. 14
Add Mail Pack From Library .............................................................................. 15
Add Mail Pack From Order ................................................................................ 15
Add Designer Template ..................................................................................... 16
Add Designer Image .......................................................................................... 17
Add Designer Stored Image .............................................................................. 17
Add Designer Text ............................................................................................. 18
Set Mail Pack Variable Value ............................................................................ 19
Set Template Variable Value ............................................................................. 19
Get Template Image .......................................................................................... 20
Add Template Use Rule .................................................................................... 20
Add Template Background Rule ........................................................................ 20
3 - Mailing Lists ..................................................................................................... 21
Add Mailing List File .......................................................................................... 21
Add Mailing List String ....................................................................................... 22
Add Mailing List From Library ............................................................................ 22

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 2
 Add Mailing List From Order .............................................................................. 23
Add Address ...................................................................................................... 23
Add Self ............................................................................................................. 24
Auto Correct Addresses .................................................................................... 25
Set Mailing List Proof Option ............................................................................. 25
4 - Delete and Cancel ........................................................................................... 26
Delete Template ................................................................................................ 26
Delete Mail Pack................................................................................................ 26
Delete Mailing List ............................................................................................. 27
Delete Mailing .................................................................................................... 27
Cancel Mailing ................................................................................................... 27
5 - Payment ........................................................................................................... 28
Process Mailing ................................................................................................. 28
Get Mailing Details ............................................................................................ 29
Get Status ......................................................................................................... 31
Get Proof File .................................................................................................... 32
Get Proof Image ................................................................................................ 32
Get Balance ....................................................................................................... 33
Get Mailing GUID From Order Ref .................................................................... 33
User Approve Mailing ........................................................................................ 33
Cancel Mailing Approval .................................................................................... 34
6 - Lists ................................................................................................................. 35
List Formats ....................................................................................................... 35
List Mailings....................................................................................................... 35
List Mailings Page Count ................................................................................... 37
List Library Templates ....................................................................................... 38
List Library Templates Page Count ................................................................... 39
List Library Backgrounds ................................................................................... 40
List Library Backgrounds Page Count ............................................................... 41
List Library Mail Packs....................................................................................... 42
List Library Mail Packs Page Count ................................................................... 43
List Library Mailing Lists .................................................................................... 44
List Library Mailing Lists Page Count ................................................................ 44
List Mailing Filter Categories ............................................................................. 45
List Mailing Filters For Category ........................................................................ 45
Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 3
 List Mailing Variable Values .............................................................................. 46
List Product Types ............................................................................................. 46
List Document Types ......................................................................................... 47
List Template Variables ..................................................................................... 48
7 - Zip Data ........................................................................................................... 49
Get Mail Pack Zip .............................................................................................. 49
Get Mailing List Zip ............................................................................................ 49
8 - Account and User Administration ..................................................................... 50
Create Account .................................................................................................. 50
Add User ........................................................................................................... 51
Add User Organisation Structure Link ............................................................... 52
Add User Sign-up Data...................................................................................... 52
9 - Mailing List Address Counts and Price Estimates ............................................ 53
Add Mailing List File For Address Count ........................................................... 53
Add Mailing List String For Address Count ........................................................ 54
Poll Mailing List For Address Count................................................................... 55
Get Mailing Price Estimate ................................................................................ 56
Get Price Estimate............................................................................................. 57
10 - Adding Library Data ....................................................................................... 58
Add Mailing List File To Library ......................................................................... 58
Add Mailing List String To Library ...................................................................... 59
Add Template File To Library ............................................................................ 60
Add Background File To Library ........................................................................ 61
Add Mail Pack To Library .................................................................................. 62
Add Template To Library Mail Pack................................................................... 62
11 - Extended Calls ............................................................................................... 63
Extended Call .................................................................................................... 63
Extended Call Definition .................................................................................... 63
Example code ........................................................................................................... 65
Adding a service reference or web reference in .NET ....................................... 65
Service Reference size limit .............................................................................. 65
Service Reference timeout limit ......................................................................... 65
VB .NET code Samples ..................................................................................... 66
Glossary of terms ..................................................................................................... 69

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 4
Overview
The following help is for the Docmail web service version 2.0. The existing version
1.1 web service and simple API are still supported, but we recommend that version
2.0 is used for all new development.

If you are not familiar with the Docmail system then please refer to the “

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 5
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.

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:
https://www.cfhdocmail.com/TestAPI2/DMWS.asmx

The testing API has an associated test website, please use this website to set-up a
test account:
https://www.cfhdocmail.com/Test

Note: Please reference the live XML schemas when using the test API.

For live:
https://www.cfhdocmail.com/LiveAPI2/DMWS.asmx

For live API use the main Docmail website, please use this website to set-up a live
account:
https://www.cfhdocmail.com/Live

Set up a Docmail account to use the web service

Using the Docmail website (see the “

Referencing the web service” 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.

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 v2.0 © 2011 CFH Total Document Management Ltd
Page 6
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.

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 v2.0 © 2011 CFH Total Document Management Ltd
Page 7
Data formats

Return Formats

Text (default)
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 https://www.cfhdocmail.com/LiveAPI2/Result.xsd. Example
result XML data:

<?xml version="1.0" encoding="utf-8" ?>

<result xmlns="https://www.cfhdocmail.com/LiveAPI2/Result.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
https://www.cfhdocmail.com/LiveAPI2/Result.xsd
https://www.cfhdocmail.com/LiveAPI2/Result.xsd">
<data>
<key>MailingGUID</key>
<value>00000000-0000-0000-0000-000000000000</value>
</data>
</result>

Template File Formats

The following template file formats are supported:

Word document (.doc or .docx)
Rich Text Format (.rtf)
Portal Document Format (.pdf)

If Word documents are encrypted or contain protected area passwords then the
relevant passwords must be supplied to remove the protection whilst processing.

Mailing List File Formats

The following mailing list file formats are supported:

Excel file (.xls or xlsx)
Comma Separated Values (.csv)
Text file (.txt) for delimited (defaults as tab delimited) or fixed length column
formats
XML file (.xml) conforming to the DataList schema that can be found at
https://www.cfhdocmail.com/LiveAPI2/DataList.xsd. An example data list xml
file can be found at
https://www.cfhdocmail.com/LiveAPI2/DataListExample.xml.
Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 8
1 - Creating Mailings

The reference calls in this section can be used to create a mailing and set the mailing
options within Docmail.

The first step in creating a mailing is to call Create File Mailing or Create Mailing.
These calls both return one or more Mailing GUIDs that can be used for all future
calls relating to the mailing.

Create File Mailing

Public Function CreateFileMailing(ByVal Username As String, ByVal Password

As String, ByVal ZipFile As Byte(), ByVal ReturnFormat As String) As String

This call allows one or more mailings to be created from a zip file without the need for
any further calls. To control the mailings an XML configuration file needs to be
included within the zip file that conforms to the Docmail Web Service schema that
can be found at https://www.cfhdocmail.com/LiveAPI2/DMWS.xsd. An example xml
file can be found at https://www.cfhdocmail.com/LiveAPI2/DMWSExample.xml.

The complex type names defined within the schema match the name of calls within
the web service. Therefore for further help on the parameters of each type you
should refer the relevant web service call, for example the “createMailing” type has
parameters that match the Create Mailing web service call.

If a configuration XML file is not included within the zip file then the call will create an
auto submit A4 letter mailing using the account default mailing options. Without an
XML file all document format files within the zip would be added as templates and all
supported mailing list file formats would be assumed to be mailing list files for import.

The create file mailing call returns “MailingGUID 1”, “MailingGUID 2” etc for each
mailing in the XML file. The Mailing GUIDs can be used to check the status or to
perform other actions on the mailing. If a mailing fails to be submitted successfully
an error will be returned, along with any Mailing GUIDs that have successfully been
saved for processing. The error message will also include the “Error processing
mailing name” to identify the mailing name that failed. Please note that if the zip
contains multiple mailings, then once a mailing fails to be created all subsequent
mailings within the zip file will not have been created. Once all mailings are created
any errors in processing will only affect the single mailing.
Parameter Data Type / Description
Max length
Username String(30) Docmail user name.
Password String(30) Password for the user
ZipFile Byte Array A zip archive file containing all the other files that
require processing. An XML file should be included
that references how to use the other files within the zip
archive.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 9
Create Mailing

Public Function CreateMailing(ByVal Username As String, ByVal Password As

String, ByVal CustomerApplication As String, ByVal ProductType As String,
ByVal MailingName As String, ByVal MailingDescription As String,
ByVal IsMono As Boolean, ByVal IsDuplex As Boolean, ByVal DeliveryType As
String, ByVal CourierDeliveryToSelf As Boolean, ByVal DespatchASAP As
Boolean, ByVal DespatchDate As Date, ByVal AddressNamePrefix As String,
ByVal AddressNameFormat As String, ByVal DiscountCode As String, ByVal
MinEnvelopeSize As String, ByVal ReturnFormat As String) As String

This call adds a new mailing to the account using the parameters defined. This call
returns a mailing GUID that can be used to add data to the mailing.
Parameter Data Type / Description
Max length
Username String(30) Docmail user name.
Password String (30) Password for the user.
CustomerApplication String(50) An optional identification of the software creating the
mailing.
ProductType String Specify as “A4Letter”, “BusinessCard”, “GreetingCard”,
or “Postcard”. If not supplied then defaults as specified
in default mailing options. The product type must be
available for your account, for example business cards
are currently only available for corporate accounts,
please see the Docmail website to confirm the
products available.
MailingName String(50) An optional name for the mailing.
MailingDescription String(50) An optional description for the mailing.
IsMono Boolean Control if the mailing is printed in black and white (true)
or colour (false).
IsDuplex Boolean Control if the mailing is double sided (true) or single
sided (false).
DeliveryType String Specify as “First”, “Standard” or “Courier”. If not
supplied then defaults as specified in default mailing
options.
CourierDeliveryToSelf Boolean If the delivery type is courier then specify whether to
despatch the order to the user’s address.
DespatchASAP Boolean Whether to despatch the mailing as soon as possible.
If set then the despatch date is ignored.
DespatchDate Date The date to despatch the order on. The Despatch
ASAP must be set to false.
AddressNamePrefix String(30) A prefix for the address name, e.g. “To the parent of”.
AddressNameFormat String Specify as “Full Name”, “Firstname Surname”, “Title
Initial Surname”, “Title Surname”, or “Title Firstname
Surname”. If not supplied then defaults as specified in
default mailing options.
DiscountCode String(20) A discount code to apply to the mailing. If not supplied
then defaults as specified in default mailing options.
MinEnvelopeSize String Specify as “C4”, “C5” or leave blank. If not supplied
then defaults as specified in default mailing options.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 10
Add Mailing Filter

Public Function AddMailingFilter(ByVal Username As String, ByVal Password

As String, ByVal MailingGUID As System.Guid, ByVal CategoryName As String,
ByVal FilterValue As String, ByVal ReturnFormat As String) As String

This call is for corporate users only and adds a mailing filter to the mailing.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
CategoryName String(50) The mailing filter category as displayed as the label on
the mailing options screen in the Docmail website.
FilterValue String The mailing filter value as displayed as in the drop
down list on the mailing options screen in the Docmail
website.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Add Delivery Address

Public Function AddDeliveryAddress(ByVal Username As String, ByVal Password

As String, ByVal MailingGUID As System.Guid, ByVal Address1 As String,
ByVal Address2 As String, ByVal Address3 As String, ByVal Address4 As
String, ByVal Address5 As String, ByVal Address6 As String, ByVal Title As
String, ByVal FirstName As String, ByVal Surname As String, ByVal Fullname
As String, ByVal JobTitle As String, ByVal CompanyName As String, ByVal
ReturnFormat As String) As String

This call is for courier despatch orders only and adds a delivery address to the order.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
Address1 String(50) Address line 1.
Address2 String(50) Address line 2.
Address3 String(50) Address line 3.
Address4 String(50) Address line 4.
Address5 String(50) Address line 5.
Address6 String(50) Address line 6.
Title String(15) The title of the person receiving the delivery.
FirstName String(30) The first name of the person receiving the delivery.
Surname String(30) The surname of the person receiving the delivery.
Fullname String(100) The full name of the person receiving the delivery.
JobTitle String(60) The job title of the person receiving the delivery.
CompanyName String(50) The company name to include on the delivery address.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 11
Update Mailing Options

Public Function UpdateMailingOptions(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal MailingName As
String, ByVal MailingDescription As String, ByVal IsMono As Boolean, ByVal
IsDuplex As Boolean, ByVal DeliveryType As String, ByVal DespatchASAP As
Boolean, ByVal DespatchDate As Date, ByVal AddressNamePrefix As String,
ByVal AddressNameFormat As String, ByVal DiscountCode As String, ByVal
MinEnvelopeSize As String, ByVal ReturnFormat As String) As String

This call updates the mailing options for a given mailing GUID.
Parameter Data Type / Description
Max length
Username String(30) Docmail user name.
Password String (30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
MailingName String(50) An optional name for the mailing.
MailingDescription String(50) An optional description for the mailing.
IsMono Boolean Control if the mailing is printed in black and white (true)
or colour (false).
IsDuplex Boolean Control if the mailing is double sided (true) or single
sided (false).
DeliveryType String Specify as “First”, “Standard” or “Courier”. If not
supplied then defaults as specified in default mailing
options.
DespatchASAP Boolean Whether to despatch the mailing as soon as possible.
If set then the despatch date is ignored.
DespatchDate Date The date to despatch the order on. The Despatch
ASAP must be set to false.
AddressNamePrefix String(30) A prefix for the address name, e.g. “To the parent of”.
AddressNameFormat String Specify as “Full Name”, “Firstname Surname”, “Title
Initial Surname”, “Title Surname”, or “Title Firstname
Surname”. If not supplied then defaults as specified in
default mailing options.
DiscountCode String(20) A discount code to apply to the mailing. If not supplied
then defaults as specified in default mailing options.
MinEnvelopeSize String Specify as “C4”, “C5” or leave blank. If not supplied
then defaults as specified in default mailing options.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 12
2 - Mail Packs

The referenced calls in this section can be used to add mail pack data to a mailing.

Add Template File

Public Function AddTemplateFile(ByVal Username As String, ByVal Password As

String, ByVal MailingGUID As System.Guid,ByVal TemplateName As String,
ByVal FileName As String, ByVal FileData As Byte(), ByVal DocumentType As
String, ByVal AddressedDocument As Boolean, ByVal AddressFontCode As
String, ByVal TemplateType As String, ByVal BackgroundName As String, ByVal
CanBeginOnBack As Boolean, ByVal NextTemplateCanBeginOnBack As Boolean,
ByVal ProtectedAreaPassword As String, ByVal EncryptionPassword As String,
ByVal BleedSupplied As Boolean, ByVal Copies As Integer, ByVal Instances As
Integer, ByVal InstancePageNumbers As String, ByVal CycleInstancesOnCopies
As Boolean, ByVal ReturnFormat As String) As String

This call adds a template document to the mailing. This call returns a template GUID
that can be used to add a background file or variable values.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
Template Name String(50) A name to refer to the template by. Optional, defaults
to the file name if not supplied.
FileName String(255) The template file name, must be in .doc, .docx, .rtf or
.pdf format.
FileData Byte Array The template file data.
DocumentType String Specify as “A4Letter”, “BusinessCard”,
“GreetingCardA5”, “PostcardA5”, “PostcardA6”,
“PostcardA5Right” or “PostcardA6Right”. Postcard A5
and A6 have a left side address panel; use the Right
variations for a right side address panel. The
document type must be available for your account, for
example business cards are currently only available for
corporate accounts, please see the Docmail website to
confirm the document types available.
AddressedDocument Boolean Add the address panel to the document. The first
template uploaded onto a mail pack will be
automatically set as an addressed document.
AddressFontCode String Specify as "Arial 10", "Arial 11", "Arial 12", "Arial 13",
"Arial 14", "Courier 10", "Courier 11", "Courier 12",
"Courier 13", "Courier 14", "Gotham 9", "Gotham 10",
"Gotham 12", "Helvetica 12", "Helvetica 13", "Helvetica
14", "MetaOT 10", "MetaOT 11", "MetaOT 12",
"Trebuchet 10", "Trebuchet 11", "Trebuchet 12",
"Verdana 10", "Verdana 11", or "Verdana 12". Defaults
to “Arial 10”.
TemplateType String Specify as “Document” or “Preformatted Stream”.
Defaults to “Document”.
BackgroundName String(120) Optional name of a background to use from the library.
CanBeginOnBack Boolean For duplex printing only, can this template begin on the
back of another template?
NextTemplateBegin Boolean For duplex printing only, can another template begin on
Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 13
CanBeginOnBack the back of this template?
ProtectedAreaPassword String(255) Password for protected areas in the document.
EncryptionPassword String(255) Password for an encrypted document.
BleedSupplied Boolean For products that support bleed only, has the bleed
been supplied.
Copies Integer Defaults to 1, other value only available for products
that support copies, must match a value available on
the delivery address screen in the Docmail website.
Instances Integer The number of instances of a document within a PDF
file. Currently only available for fixed page document
formats.
InstancePageNumbers String Functionality not yet implemented. A comma
separated list of page numbers to identify the instances
for a non fixed page document format.
CycleInstancesOnCopies Boolean Only available for products that support copies, if true a
different instance is used for each copy.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Add Template Background File

Public Function AddTemplateBackgroundFile(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal TemplateGUID
As System.Guid, ByVal BackgroundName As String, ByVal FileName As String,
ByVal FileData As Byte(),ByVal EncryptionPassword As String, ByVal
ReturnFormat As String) As String

This call allows a background file to be added against a specific template on a

mailing.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
TemplateGUID GUID The template to add the background against.
Background name String(120) The name of the background, defaults to the file name
if not supplied.
FileName String(255) The background file name, must be in .doc, .docx, .rtf
or .pdf format.
FileData Byte Array The background file data.
EncryptionPassword String(255) Password for an encrypted document.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 14
Add Template From Library

Public Function AddTemplateFromLibrary(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal TemplateName As
String, ByVal Copies As Integer, ByVal ReturnFormat As String) As String

This call adds a template from the library. This call returns a template GUID that can
be used to add a background file or set variable values. For corporate users this call
can also be used to add inserts to a mailing, supplying the insert name as the
template name parameter.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
TemplateName String(50) The name of the template from the library. If there is
more than one template in the library with the same
name the template that was created first is used.
Copies Integer Defaults to 1, other value only available for products
that support copies, must match a value available on
the delivery address screen in the Docmail website.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Add Template From Order

Public Function AddTemplateFromOrder(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal OrderRef As
Long, ByVal TemplateName As String, ByVal Copies As Integer, ByVal
ReturnFormat As String) As String

This call adds a template from a previous order to the current mailing. This call
returns a template GUID that can be used to add a background file or set variable
values.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
OrderRef Long The order reference for the previous order.
TemplateName String(50) The name of the template on the order. If there is
more than one template on the order with the same
name the template then the first template on the mail
pack is used.
Copies Integer Defaults to 1, other value only available for products
that support copies, must match a value available on
the delivery address screen in the Docmail website.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 15
Add Mail Pack From Library

Public Function AddMailPackFromLibrary(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal MailPackName As
String, ByVal ReturnFormat As String) As String

This call adds a mail pack from the library. This call returns a mail pack GUID that
can be used to set variable values along with TemplateGUID 1, TemplateGUID 2 etc
for each template that has been added.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
MailPackName String(50) The name of the mail pack in the library. If there is
more than one mail pack in the library with the same
name the mail pack that was created first is used.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Add Mail Pack From Order

Public Function AddMailPackFromOrder(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal OrderRef As
Long, ByVal ReturnFormat As String) As String

This call adds a mail pack from a previous order to the current mailing. This call
returns a mail pack GUID that can be used to set variable values along with
TemplateGUID 1, TemplateGUID 2 etc for each template that has been added.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
OrderRef Long The order reference for the previous order.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 16
Add Designer Template

Public Function AddDesignerTemplate(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal TemplateLayout
As String, ByVal DocumentType As String, ByVal AddressFontCode As String,
ByVal BleedSupplied As Boolean, ByVal Copies As Integer, ByVal
SkipPreviewImageGeneration As Boolean, ByVal ReturnFormat As String) As
String

This call adds a designer template to the current mailing, allowing the creation of
postcards and greeting cards by uploading or selecting the parts that make up the
final template. Only one designer template can be added to a mailing.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
TemplateLayout String(100) Must match the name of a template layout as listed in
the designer on the Docmail website.
DocumentType String Specify as “A4Letter”, “BusinessCard”,
“GreetingCardA5”, “PostcardA5”, “PostcardA6”,
“PostcardA5Right” or “PostcardA6Right”. Postcard A5
and A6 have a left side address panel; use the Right
variations for a right side address panel. The
document type must be available for your account, for
example business cards are currently only available for
corporate accounts, please see the Docmail website to
confirm the document types available.
AddressFontCode String Specify as "Arial 10", "Arial 11", "Arial 12", "Arial 13",
"Arial 14", "Courier 10", "Courier 11", "Courier 12",
"Courier 13", "Courier 14", "Gotham 9", "Gotham 10",
"Gotham 12", "Helvetica 12", "Helvetica 13", "Helvetica
14", "MetaOT 10", "MetaOT 11", "MetaOT 12",
"Trebuchet 10", "Trebuchet 11", "Trebuchet 12",
"Verdana 10", "Verdana 11", or "Verdana 12". Defaults
to “Arial 10”.
BleedSupplied Boolean For products that support bleed only, has the bleed
been supplied in the template. If false then Docmail
will add white space to allow for the bleed.
Copies Integer Defaults to 1, other value only available for products
that support copies, must match a value available on
the delivery address screen in the Docmail website.
SkipPreview Boolean Skip the preview image generation when producing the
ImageGeneration order. Setting to true will speed up the processing of
the mailing but will not display any images when
viewing in the website.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 17
Add Designer Image

Public Function AddDesignerImage(ByVal Username As String, ByVal Password

As String, ByVal MailingGUID As System.Guid, ByVal PartDisplayName As
String, ByVal FileName As String, ByVal FileData As Byte(), ByVal
ImageRotation As Double, ByVal ImageFitOption As String, ByVal ReturnFormat
As String) As String

This call adds an image file to a designer template.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
PartDisplayName String(100) Must match the part name as displayed in the
properties panel on the Docmail website.
FileName String(255) The file name, must be in .jpg, .jpeg, .bmp, .gif, .png,
.tif or .tiff format.
FileData Byte Array The image file data.
ImageRotation Double The degrees or rotation of the image; must be set to 0,
90, 180 or 270.
ImageFitOption String Specify as “Crop” or “Resize to Fit”.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Add Designer Stored Image

Public Function AddDesignerStoredImage(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal PartDisplayName
As String, ByVal ImageName As String, ByVal ImageRotation As Double, ByVal
ImageFitOption As String, ByVal ReturnFormat As String) As String

This call adds a stored image to a designer template.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
PartDisplayName String(100) Must match the part name as displayed in the
properties panel on the Docmail website.
ImageName String(50) Must match the image name as displayed in the list of
images for the part on the Docmail website.
ImageRotation Double The degrees or rotation of the image; must be set to 0,
90, 180 or 270.
ImageFitOption String Specify as “Crop” or “Resize to Fit”.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 18
Add Designer Text

Public Function AddDesignerText(ByVal Username As String, ByVal Password As

String, ByVal MailingGUID As System.Guid, ByVal PartDisplayName As String,
ByVal TextContent As String, ByVal FontSize As Integer, ByVal FontName As
String, ByVal Bold As Boolean, ByVal Italic As Boolean, ByVal Underline As
Boolean, ByVal TextJustification As String, ByVal FontColourRed As Integer,
ByVal FontColourGreen As Integer, ByVal FontColourBlue As Integer, ByVal
ReturnFormat As String) As String

This call adds a stored image to a designer template.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
PartDisplayName String(100) Must match the part name as displayed in the
properties panel on the Docmail website.
TextContent String The text to enter.
FontSize Integer The font size for the text, must be between 1 and 200.
FontName String Specify "Arial", "Courier", "Gotham Narrow Book",
"Goudy Old Style", "Helvetica", "Lucida Handwriting",
"MetaOT-Normal", "MGillSansLight", "Party LET",
"Times New Roman", "Trebuchet MS", "Verdana". If
not supplied maintains default as shown on the
Docmail website.
Bold Boolean Make the text bold.
Italic Boolean Make the text italic.
Underline Boolean Make the text underlined.
TextJustification String Specify "Center", "Full", "Left", or "Right".
FontColourRed Integer A value between 0 and 255 to represent the amount of
red for the font colour.
FontColourGreen Integer A value between 0 and 255 to represent the amount of
green for the font colour.
FontColourBlue Integer A value between 0 and 255 to represent the amount of
blue for the font colour.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 19
Set Mail Pack Variable Value

Public Function SetMailPackVariableValue(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal VariableName As
String, ByVal VariableValue As String, ByVal ReturnFormat As String) As
String

This call sets a variable value for all templates containing the variable in the mail
pack.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
VariableName String(255) Must match the variable name as displayed on the
enter variables screen in the Docmail website.
VariableValue String The text to replace or the text that matches the
displayed text in a list of options on the Docmail
website for the variable.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Set Template Variable Value

Public Function SetTemplateVariableValue(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal TemplateGUID As
System.Guid, ByVal VariableName As String, ByVal VariableValue As String,
ByVal ReturnFormat As String) As String

This call sets a variable value on a specified template.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
TemplateGUID GUID The template GUID returned from adding a template.
VariableName String(255) Must match the variable name as displayed on the
enter variables screen in the Docmail website.
VariableValue String The text to replace or the text that matches the
displayed text in a list of options on the Docmail
website for the variable.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 20
Get Template Image

Public Function GetTemplateImage(ByVal Username As String, ByVal Password

As String, ByVal TemplateGUID As System.Guid, ByVal PageNumber As Integer,
ByVal FailureReturnFormat As String) As Byte()

This call returns a byte array image preview or thumbnail. Pass the page number as
0 for the thumbnail or 1 for the large preview image.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
TemplateGUID GUID The template GUID returned from adding a template.
PageNumber String(255) Supply either 0 for the thumbnail or 1 for the large
preview image.
FailureReturnFormat String Specify as “Text” or “XML” see Return Formats.

Add Template Use Rule

Public Function AddTemplateUseRule(ByVal Username As String, ByVal Password

As String, ByVal MailingGUID As System.Guid, ByVal TemplateGUID As
System.Guid, ByVal AndGroup As String, ByVal AddressField As String, ByVal
DataFormat As String, ByVal FromEquation As String, ByVal FromData As
String, ByVal ToEquation As String, ByVal ToData As String, ByVal
ReturnFormat As String)

This functionality has not yet been implemented.

Add Template Background Rule

Public Function AddTemplateBackgroundRule(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal TemplateGUID As
System.Guid, ByVal BackgroundName As String, ByVal AndGroup As String,
ByVal AddressField As String, ByVal DataFormat As String, ByVal
FromEquation As String, ByVal FromData As String, ByVal ToEquation As
String, ByVal ToData As String, ByVal ReturnFormat As String) As String

This functionality has not yet been implemented.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 21
3 - Mailing Lists

The referenced calls in this section can be used to add addresses to a mailing.

If you are using a file or string to import data then it is recommended that a library
mapping is created in the Docmail website and the mapping name passed to the
calls. This will ensure the correct mapping of columns is always used for the import.

Add Mailing List File

Public Function AddMailingListFile(ByVal Username As String, ByVal Password

As String, ByVal MailingGUID As System.Guid, ByVal FileName As String,
ByVal FileData As Byte(), ByVal DataFormat As String, ByVal HasHeaders As
Boolean, ByVal SheetName As String, ByVal MappingDelimiter As String, ByVal
MappingFixedWidthChars As String, ByVal MappingName As String, ByVal
ReturnFormat As String) As String

This function adds the addresses from a mailing list file to the mailing. This call
returns a Mailing List GUID that can be used for obtaining address count information.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
FileName String(255) The file name must be in .csv, .txt, .xls, .xlsx or .xml
format.
FileData Byte Array The image file data.
DataFormat String Specify as "Excel", "CSV", "Tab separated",
"Delimited", or "Fixed width".
HasHeaders Boolean Does the file have a row specifying the headers?
SheetName String(31) For Excel data only, the Excel sheet name to import
from. If not supplied the first sheet in the Excel file will
be used.
MappingDelimiter String(10) For Delimited data only, the delimiter to use. If not
supplied then delimited files will be assumed to be tab
delimited.
MappingFixedWidthChars String For Fixed Width data only, a comma separated list of
the numbers of characters for each column.
MappingName String(50) The name of a library mapping to use.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 22
Add Mailing List String

Public Function AddMailingListString(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal MailingListData
As String, ByVal DataFormat As String, ByVal HasHeaders As Boolean, ByVal
SheetName As String, ByVal MappingDelimiter As String, ByVal
MappingFixedWidthChars As String, ByVal MappingName As String, ByVal
ReturnFormat As String) As String

This function adds the addresses from a formatted string to the mailing. This call
returns a Mailing List GUID that can be used for obtaining address count information.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
MailingListData String A formatted string containing the data.
DataFormat String Specify as "Excel", "CSV", "Tab separated",
"Delimited", or "Fixed width".
HasHeaders Boolean Does the file have a row specifying the headers?
SheetName String(31) For Excel data only, the Excel sheet name to import
from. If not supplied the first sheet in the Excel file will
be used.
MappingDelimiter String(10) For Delimited data only, the delimiter to use. If not
supplied then delimited files will be assumed to be tab
delimited.
MappingFixedWidthChars String For Fixed Width data only, a comma separated list of
the numbers of characters for each column.
MappingName String(50) The name of a library mapping to use.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Add Mailing List From Library

Public Function AddMailingListFromLibrary(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal MailingListName
As String, ByVal ReturnFormat As String) As String

This function adds the addresses from a library mailing list to the mailing. This call
returns a Mailing List GUID that can be used for obtaining address count information.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
MailingListName String(50) The name of the mailing list in the library. If there is
more than one mailing list in the library with the same
name the mailing list that was created first is used.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 23
Add Mailing List From Order

Public Function AddMailingListFromOrder(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal OrderRef As
Integer, ByVal ReturnFormat As String) As String

This function adds the addresses from a previous order to the mailing. This call
returns a Mailing List GUID that can be used for obtaining address count information.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
OrderRef Long The order reference for the previous order.

ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Add Address

Public Function AddAddress(ByVal Username As String, ByVal Password As

String, ByVal MailingGUID As System.Guid, ByVal Address1 As String, ByVal
Address2 As String, ByVal Address3 As String, ByVal Address4 As String,
ByVal Address5 As String, ByVal Address6 As String, ByVal UseForProof As
Boolean, ByVal Title As String, ByVal FirstName As String, ByVal Surname As
String, ByVal Fullname As String, ByVal JobTitle As String, ByVal
CompanyName As String, ByVal Email As String, ByVal Telephone As String,
ByVal DirectLine As String, ByVal Mobile As String, ByVal Facsimile As
String, ByVal ExtraInfo As String, ByVal Notes As String, ByVal
CustomerAddressID As String, ByVal CustomerImportID As String, ByVal
StreamPages1 As Integer, ByVal StreamPages2 As Integer, ByVal StreamPages3
As Integer, ByVal Custom1 As String, ByVal Custom2 As String, ByVal Custom3
As String, ByVal Custom4 As String, ByVal Custom5 As String, ByVal Custom6
As String, ByVal Custom7 As String, ByVal Custom8 As String, ByVal Custom9
As String, ByVal Custom10 As String, ByVal ReturnFormat As String) As
String

This function adds an address to the mailing.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
Address1 String(50) The first line of the address.
Address2 String(50) The second line of the address.
Address3 String(50) The third line of the address.
Address4 String(50) The fourth line of the address.
Address5 String(50) The fifth line of the address.
Address6 String(50) The sixth line of the address.
UseForProof Boolean Whether to use this address on the proof. Up to 3
addresses can be flagged as use for proof for mailing
lists of up to 500 addresses. Mailing lists with 500 or
more address can have up to 10 addresses flagged as
use for proof.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 24
Title String(15) The person’s title, e.g. Mr, Mrs etc.
FirstName String(30) The person’s first name.
Surname String(30) The person’s surname.
FullName String(100) The person’s full name. If not defined is defaulted to
Firstname and Surname.
JobTitle String(60) The person’s job title.
CompanyName String(50) The person’s company.
Email String(70) The person’s email address
Telephone String(20) The person’s telephone number.
DirectLine String(20) The person’s direct line telephone number.
Mobile String(20) The person’s mobile telephone number.
Facsimile String(20) The person’s fax number.
ExtraInfo String(50) Extra information.
Notes String(100) Notes.
CustomerAddressID String(100) Your own identification for this address.
CustomerImportID String(100) Your own identification for this set of addresses.
StreamPages1 Integer The number of pages to use from the first template on
the mail pack that is defined as “Preformatted Stream”.
The total pages for all addresses must match the total
number of pages in the template.
StreamPages2 Integer The number of pages to use from the second template
on the mail pack that is defined as “Preformatted
Stream”. The total pages for all addresses must match
the total number of pages in the template.
StreamPages3 Integer The number of pages to use from the third template on
the mail pack that is defined as “Preformatted Stream”.
The total pages for all addresses must match the total
number of pages in the template.
Custom1 String(50) Custom data.
Custom2 String(50) Custom data.
Custom3 String(50) Custom data.
Custom4 String(50) Custom data.
Custom5 String(50) Custom data.
Custom6 String(50) Custom data.
Custom7 String(50) Custom data.
Custom8 String(50) Custom data.
Custom9 String(50) Custom data.
Custom10 String(50) Custom data.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Add Self

Public Function AddSelf(ByVal Username As String, ByVal Password As String,

ByVal MailingGUID As System.Guid, ByVal ReturnFormat As String) As String

This function adds the speficied user’s address to the mailing.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 25
Auto Correct Addresses

Public Function AutoCorrectAddresses(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal
CorrectionMethod As String, ByVal ReturnFormat As String) As String

This function applies correction to the addresses after all the addresses have been
added to the mailing.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
CorrectionMethod String Specify as "All", "Cost", or "Original".
"All" = Auto correct wherever correctable address is
detected.
"Cost"= Auto correct only when it will reduce the cost
of the postage.
"Original" = Revert to original address uncorrected
addresses.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Set Mailing List Proof Option

Public Function SetMailingListProofOption(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, _
ByVal ProofOption As String, ByVal
ReturnFormat As String) As String

This function applies proof option to the addresses after all the addresses have been
added to the mailing.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
ProofOption String Specify as "Clear", "FirstMidLast", "Last", or "Longest".
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 26
4 - Delete and Cancel

The referenced calls in this section can be used to delete a mailing, delete data from
a mailing or cancel a mailing.

Delete Template

Public Function DeleteTemplate(ByVal Username As String, ByVal Password As

String, ByVal MailingGUID As System.Guid, ByVal TemplateGUID As
System.Guid, ByVal ReturnFormat As String) As String

This call deletes a template from the mailing.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
TemplateGUID GUID The template GUID to delete.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Delete Mail Pack

Public Function DeleteMailPack(ByVal Username As String, ByVal Password As

String, ByVal MailingGUID As System.Guid, ByVal ReturnFormat As String) As
String

This call deletes all templates from the mailing.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 27
Delete Mailing List

Public Function DeleteMailingList(ByVal Username As String, ByVal Password

As String, ByVal MailingGUID As System.Guid, ByVal ReturnFormat As String)
As String

This call deletes all addresses from the mailing.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Delete Mailing

Public Function DeleteMailing(ByVal Username As String, ByVal Password As

String, ByVal MailingGUID As System.Guid, ByVal ReturnFormat As String) As
String

This call deletes a mailing.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Cancel Mailing

Public Function CancelMailing(ByVal Username As String, ByVal Password As

String, ByVal MailingGUID As System.Guid, ByVal ReturnFormat As String) As
String

This call cancels a mailing.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 28
5 - Payment

The referenced calls in this section can be used to manage the processing, payment
and proof approval.

Process Mailing

Public Function ProcessMailing(ByVal Username As String, ByVal Password As

String, ByVal MailingGUID As System.Guid, ByVal CustomerApplication As
String, ByVal Submit As Boolean, ByVal PartialProcess As Boolean, ByVal
MaxPriceExVAT As Double, ByVal POReference As String, ByVal PaymentMethod
As String, ByVal SkipPreviewImageGeneration As Boolean, ByVal
EmailSuccessList As String, ByVal EmailErrorList As String, ByVal
HttpPostOnSuccess As String, ByVal HttpPostOnError As String, ByVal
ReturnFormat As String) As String

This call submits a mailing for processing.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
CustomerApplication String(50) An optional identification of the software creating the
mailing. Note that if the customer application has
already been supplied on the Create Mailing call then it
will not be updated if left blank on this call.
Submit Boolean Submit the mailing once processing is complete.
PartialProcess Boolean Is there only partial data for processing? This flag is
ignored if Submit is set to True. If set to False then an
error is raised if a full set of data required to process a
mailing has not been supplied. If set to True then the
processing stops before approval.
MaxPriceExVAT Double Specify a maximum amount that the order can cost to
allow the order submission to succeed. Leave as
blank for no limit.
POReference String(30) Your purchase order reference for this mailing, for
invoice payment only.
PaymentMethod String Specify as “Invoice” or “Topup”. If not supplied
defaults to “Invoice” if the account can pay on invoice,
otherwise defaults to pay from Topup credit.
SkipPreview Boolean Skip the preview image generation when producing the
ImageGeneration order. Setting to true will speed up the processing of
the mailing but will not display any images when
viewing in the website.
EmailSuccessList String(1000) A semi-colon separated list of email addresses to email
once the processing of the mailing is successful.
EmailErrorList String(1000) A semi-colon separated list of email addresses to email
when the processing of a mailing fails.
HttpPostOnSuccess String(500) A web http URL to call on success of the mailing. The
request parameters included are:
MailingGUID GUID
OrderRef Long
Success Boolean

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 29
HttpPostOnError String(500) A web http URL to call on error of the mailing. The
request parameters included are:
MailingGUID GUID
OrderRef Long
Success Boolean
Failure String
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Get Mailing Details

Public Function GetMailingDetails(ByVal Username As String, ByVal Password

As String, ByVal MailingGUID As System.Guid, ByVal ReturnFormat As String)
As String

This call gets the details of the mailing.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

This call returns the following data in the specified return format:

Data item Description

Order ref The order reference for the mailing.

Mailing name The mailing name.

Product type The mailing product type.
Created The date the order was created.
Status code The current status of the mailing.
Has Paid? Has the order been paid? When paying on invoice this will
only be true once the invoice payment has cleared.
Price inc VAT The total price for the mailing including Value Added Tax.
Price ex VAT The total price for the mailing excluding Value Added Tax.
VAT rate The current VAT rate, e.g. 20 is returned for 20%.
VAT The amount of VAT for the mailing.
Estimated delivery date The estimated delivery date for the mailing based upon
normal mailing demand.
Is duplex? Is the mailing going to be duplex printed?
Is colour? Is the mailing going to be printed in colour?
Despatch type Is the mailing being despatched standard class, first class
or by courier?
Despatch date Returns the despatch date or “ASAP”.
Submitted for printing? Has the mailing been submitted for printing?
Template count The number of templates on the mailing.
Insert count The number of inserts on the mailing. Only returned if there
is at least one insert on the mailing.
Mailing list address count The total number of addresses imported onto the mailing
list. Only returned if the mailing has a mailing list.
Mailing list bad address count Corporate option only. A count of the bad addresses on the
mailing list that will not be sent. Only returned if account
address preference is set to not allow bad addresses and
once the mailing list addresses have been validated.
Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 30
Mailing list cheapest postal rate A count of the addresses that qualify for the cheapest
address count postal rates. Only returned once the mailing list addresses
have been validated.
Mailing list can correct address count A count of the addresses that can be corrected. Only
returned once the mailing list addresses have been
validated.

Mailing list corrected address count A count of the addresses that have been corrected. Only
returned once the mailing list addresses have been
validated.
Mailing list good address count A count of the addresses that have been validated. Only
returned once the mailing list addresses have been
validated.
Mailing list not validated address A count of the addresses that have not been validated.
count Only returned once the mailing list addresses have been
validated.
Mailing list western Europe count A count of the western Europe addresses. Only returned
once the mailing list addresses have been validated.
Mailing list rest of the world count A count of the rest of the world addresses. Only returned
once the mailing list addresses have been validated.
Mailing list surcharge postage A count of addresses that will incur a postal surcharge.
Only returned once the mailing list addresses have been
validated.
Mailing list missing field total address The number of addresses that have missing tags that are
count used in the mail pack. Only returned if the mailing has
missing fields.
Mailing list missing field address The count of addresses for each individual field that is
count for field [Field name] missing. Only returned if the mailing has missing fields.
Proof print sheets The number of sheets of paper used for the proof. Only
returned if a proof has been generated.
Proof print sides The number of sides of print on the proof. Only returned if
a proof has been generated.
C4 envelope count A count of the number of C4 envelopes that will be sent.
Only returned if there is more than one C4 envelope and a
proof has been generated.
C5 envelope count A count of the number of C5 envelopes that will be sent.
Only returned if there is more than one C5 envelope and a
proof has been generated.
Standard class postage address The number of addresses that will be sent standard class.
count Only returned if a proof has been generated.
Surcharge standard postage address The number of addresses that will be standard class but
count with a surcharge applied. Only returned if a proof has been
generated.
First class postage address count The number of first class addresses that will be sent. Only
returned if a proof has been generated.
Overseas postage address count The number of overseas addresses that will be sent. Only
returned if a proof has been generated.
Missing referenced font list Returns a list of fonts that will be substituted in the proof as
they have not been embedded into the document. Only
returned if a proof has been generated.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 31
Get Status

Public Function GetStatus(ByVal Username As String, ByVal Password As

String, ByVal MailingGUID As System.Guid, ByVal ReturnFormat As String) As
String

This call gets the processing status of the mailing.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

This call returns one of the following statuses:

Status Description
Error in processing The process has errored, a failure message
should be sent to specified email list or
added to the HttpPostOnError.

Awaiting submitting for processing The process mailing call has not been made.

Partial processing complete The partial processing has completeded

successfully.
Processing mailing list A mailing list for address counts is still being
processed.
Mailing list processed A mailing list for address counts has been
processed successfully.
Awaiting processing The mailing has been submitted for
processing but the processing has not yet
begun.
Processing mailing - generating designer template The processing is incomplete and is currently
generating the designer template.
Processing mailing - importing templates The processing is incomplete and is currently
importing templates.
Processing mailing - importing addresses The processing is incomplete and is currently
importing addresses.
Processing mailing - validating addresses The processing is incomplete and is currently
validating addresses.
Processing mailing - generating proof The processing is incomplete and is currently
generating a proof.
Processing mailing - approving mailing The processing is incomplete and is currently
approving a mailing.
Mailing submitted The processing is complete and the mailing
has been submitted.
Mailing processed The mailing has been fully processed, but
has not been submitted.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 32
Get Proof File

Public Function GetProofFile(ByVal Username As String, ByVal Password As

String, ByVal MailingGUID As System.Guid, ByVal FailureReturnFormat As
String) As Byte()

This call gets the PDF proof file for the mailing. The mailing must have been fully
processed before using this call, otherwise a failure will be returned.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
FailureReturnFormat String Specify as “Text” or “XML” see Return Formats.

Get Proof Image

Public Function GetProofFile(ByVal Username As String, ByVal Password As

String, ByVal MailingGUID As System.Guid, ByVal FailureReturnFormat As
String) As Byte()

This call gets the PNG format proof image file for a given page. The mailing must
have been fully processed before using this call, otherwise a failure will be returned.
This call will also fail if the skip preview image generation is set to true on the
process mailing call.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
PageNumber Integer The page number to return an image for. Supply 0 to
get an index image containing a thumbnail of each
page.
FailureReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 33
Get Balance

Public Function GetBalance(ByVal Username As String, ByVal Password As

String, ByVal AccountType As String, ByVal ReturnFormat As String) As
String

This call get the current balance for the given account type. Returns Current Balance
for a top-up account, or Credit Limit, Credit Available and Amount owed for an
invoice account.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
AccountType String Specify as “Invoice” or “Topup”.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Get Mailing GUID From Order Ref

Public Function GetMailingGUIDFromOrderRef(ByVal Username As String, ByVal

Password As String, ByVal OrderRef As Long, ByVal ReturnFormat As String)
As String

This call gets the mailing GUID for a given order reference.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
OrderRef Long The order ref to retrieve the GUID for.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

User Approve Mailing

Public Function UserApproveMailing(ByVal Username As String, ByVal Password

As String, ByVal MailingGUID As System.Guid, ByVal ReturnFormat As String)
As String

This call user approves the mailing. Please note that the mailing will be submitted if
there is no further corporate approval required and auto submission is enabled on the
account; otherwise the mailing can be submitted by calling Process Mailing.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 34
Cancel Mailing Approval

Public Function CancelMailingApproval(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal ReturnFormat As
String) As String

This call cancels all approval on the mailing, allowing the mailing to be edited.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 35
6 - Lists

The referenced calls in this section can be used to obtain lists of data.

List Formats

List methods all have a list format, this can be specified as:

CSV (default)
The string returned will be in CSV format, with the first row containing the headers.

XML
An XML string conforming to the DataList schema that can be found at
https://www.cfhdocmail.com/LiveAPI2/DataList.xsd

List Mailings

Public Function ListMailings(ByVal Username As String, ByVal Password As

String, ByVal ProductType As String, ByVal SubmittedFrom As Date, ByVal
SubmittedTo As Date, ByVal SearchText As String, ByVal OutstandingOnly As
Boolean, ByVal AllUsers As Boolean, ByVal CanContentApproveOnly As Boolean,
ByVal CanBudgetApproveOnly As Boolean, ByVal CustomerApplication As String,
ByVal PageSize As Integer, ByVal PageNumber As Integer, ByVal SortColumn As
String, ByVal SortDescending As Boolean, ByVal ListFormat As String, ByVal
FailureReturnFormat As String) As String

This call retrieves a list of mailings.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
ProductType String Specify as “A4Letter”, “BusinessCard”, “GreetingCard”,
or “Postcard”. If not supplied then defaults as specified
in default mailing options. The product type must be
available for your account, for example business cards
are currently only available for corporate accounts,
please see the Docmail website to confirm the
products available.
SubmittedFrom DateTime Restrict orders to only those submitted after the
specified date.
SubmittedTo DateTime Restrict orders to only those submitted before the
specified date.
SearchText String(100) Search the order references and mailing name on the
search text.
OutstandingOnly Boolean Only return orders that have not been submitted.
AllUsers Boolean Return mailings from other users that this user has
permission to view.
CanContentApproveOnly Boolean Return only mailings that this user can content
approve.
CanBudgetApproveOnly Boolean Return only mailings that this user can budget approve.
Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 36
CustomerApplication String(50) Return only mailings created by a specific customer
application.
PageSize Integer Specify the number of results per page, must be
between 1 and 50.
PageNumber Integer The page of results to return. Use the List Mailings
Page Count call to return how many pages are
available.
SortColumn String Specify one of the returned columns, see the list
below. Defaults to “Order ref” if not supplied.
SortDescending Boolean Sort the specified sort column descending.
ListFormat String Specify as “CSV” or XML see List Formats.
FailureReturnFormat String Specify as “Text” or “XML” see Return Formats.

This call returns the following columns of data ordered by latest order reference first:

Column header Data type Description

Mailing GUID GUID The mailing GUID.
Order ref Long The mailing order reference.
Mailing name String The mailing name.
Submitted for printing Yes/No Has the mailing been submitted for printing?
Status String The current status of the mailing.
Despatch ASAP Yes/No Is the mailing being despatched ASAP?
Despatch date Date The mailing despatch date.
Estimated delivery date Date The estimated delivery date for the mailing based upon
normal mailing demand.
Price ex VAT Double The total price for the mailing excluding Value Added
Tax in GBP.
VAT rate Double The current VAT rate percentage, e.g. 20 is returned
for a 20% VAT rate.
VAT Double The amount of VAT for the mailing in GBP.
Price inc VAT Double The total price for the mailing including Value Added
Tax in GBP.
Has Paid? Yes/No Has the order been paid? When paying on invoice this
will only be true once the invoice payment has cleared.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 37
List Mailings Page Count

Public Function ListMailingsPageCount(ByVal Username As String, ByVal

Password As String, ByVal ProductType As String, ByVal SubmittedFrom As
Date, ByVal SubmittedTo As Date, ByVal SearchText As String, ByVal
OutstandingOnly As Boolean, ByVal AllUsers As Boolean, ByVal
CanContentApproveOnly As Boolean, ByVal CanBudgetApproveOnly As Boolean,
ByVal CustomerApplication As String, ByVal PageSize As Integer, ByVal
ReturnFormat As String) As String

This call retrieves the page count for a list of mailings, returns a page count of zero if
no mailings are found for the search criteria.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
ProductType String Specify as “A4Letter”, “BusinessCard”, “GreetingCard”,
or “Postcard”. If not supplied then defaults as specified
in default mailing options. The product type must be
available for your account, for example business cards
are currently only available for corporate accounts,
please see the Docmail website to confirm the
products available.
SubmittedFrom DateTime Restrict orders to only those submitted after the
specified date.
SubmittedTo DateTime Restrict orders to only those submitted before the
specified date.
SearchText String(100) Search the order references and mailing name on the
search text.
OutstandingOnly Boolean Only return orders that have not been submitted.
AllUsers Boolean Return mailings from other users that this user has
permission to view.
CanContentApproveOnly Boolean Return only mailings that this user can content
approve.
CanBudgetApproveOnly Boolean Return only mailings that this user can budget approve.
CustomerApplication String(50) Return only mailings created by a specific customer
application.
PageSize Integer Specify the number of results per page, must be
between 1 and 50.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 38
List Library Templates

Public Function ListLibraryTemplates(ByVal Username As String, ByVal

Password As String, ByVal ProductType As String, ByVal
AddressedDocumentsOnly As Boolean, ByVal SearchText As String, ByVal
Inserts As Boolean, ByVal PageSize As Integer, ByVal PageNumber As Integer,
ByVal SortColumn As String, ByVal SortDescending As Boolean, ByVal
ListFormat As String, ByVal FailureReturnFormat As String) As String

This call retrieves a list of library templates.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
ProductType String Specify as “A4Letter”, “BusinessCard”, “GreetingCard”,
or “Postcard”. If not supplied then defaults as specified
in default mailing options. The product type must be
available for your account, for example business cards
are currently only available for corporate accounts,
please see the Docmail website to confirm the products
available.
AddressedDocumentsOnly Boolean Return addresses documents only?
SearchText String(100) Search the template names using the supplied search
text.
Inserts Boolean Set to false to return templates or true to return inserts.
PageSize Integer Specify the number of results per page, must be
between 1 and 50.
PageNumber Integer The page of results to return. Use the List Library
Templates Page Count call to return how many pages
are available.
SortColumn String Specify one of the returned columns, see the list below.
Defaults to “Template Name” if not supplied.
SortDescending Boolean Sort the specified sort column descending.
ListFormat String Specify as “CSV” or XML see List Formats.
FailureReturnFormat String Specify as “Text” or “XML” see Return Formats.

This call returns the following columns:

Column header Data type Description

Template name String The template name

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 39
List Library Templates Page Count

Public Function ListLibraryTemplatesPageCount(ByVal Username As String,

ByVal Password As String, ByVal ProductType As String, ByVal
AddressedDocumentsOnly As Boolean, ByVal SearchText As String, ByVal
Inserts As Boolean, ByVal PageSize As Integer, ByVal ReturnFormat As
String) As String

This call retrieves the page count for a list of library templates, returns a page count
of zero if no templates are found for the search criteria.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
ProductType String Specify as “A4Letter”, “BusinessCard”, “GreetingCard”,
or “Postcard”. If not supplied then defaults as specified
in default mailing options. The product type must be
available for your account, for example business cards
are currently only available for corporate accounts,
please see the Docmail website to confirm the products
available.
AddressedDocumentsOnly Boolean Return addresses documents only?
SearchText String(100) Search the template names using the supplied search
text.
Inserts Boolean Set to false to return templates or true to return inserts.
PageSize Integer Specify the number of results per page, must be
between 1 and 50.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 40
List Library Backgrounds

Public Function ListLibraryBackgrounds(ByVal Username As String, ByVal

Password As String, ByVal ProductType As String, ByVal SearchText As
String, ByVal PageSize As Integer, ByVal PageNumber As Integer, ByVal
SortColumn As String, ByVal SortDescending As Boolean, ByVal ListFormat As
String, ByVal FailureReturnFormat As String) As String

This call retrieves a list of library backgrounds.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
ProductType String Specify as “A4Letter”, “BusinessCard”, “GreetingCard”,
or “Postcard”. If not supplied then defaults as specified
in default mailing options. The product type must be
available for your account, for example business cards
are currently only available for corporate accounts,
please see the Docmail website to confirm the products
available.
SearchText String(100) Search the background names using the supplied
search text.
PageSize Integer Specify the number of results per page, must be
between 1 and 50.
PageNumber Integer The page of results to return. Use the List Library
Backgrounds Page Count call to return how many
pages are available.
SortColumn String Specify one of the returned columns, see the list below.
Defaults to “Background Name” if not supplied.
SortDescending Boolean Sort the specified sort column descending.
ListFormat String Specify as “CSV” or XML see List Formats.
FailureReturnFormat String Specify as “Text” or “XML” see Return Formats.

This call returns the following columns of data ordered by background name and
created on date:

Column header Data type Description

Background name String The background name

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 41
List Library Backgrounds Page Count

Public Function ListLibraryBackgroundsPageCount(ByVal Username As String,

ByVal Password As String, ByVal ProductType As String, ByVal SearchText As
String, ByVal PageSize As Integer, ByVal ReturnFormat As String) As String

This call retrieves the page count for a list of library backgrounds, returns a page
count of zero if no backgrounds are found for the search criteria.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
ProductType String Specify as “A4Letter”, “BusinessCard”, “GreetingCard”,
or “Postcard”. If not supplied then defaults as specified
in default mailing options. The product type must be
available for your account, for example business cards
are currently only available for corporate accounts,
please see the Docmail website to confirm the products
available.
SearchText String(100) Search the background names using the supplied
search text.
PageSize Integer Specify the number of results per page, must be
between 1 and 50.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 42
List Library Mail Packs

Public Function ListLibraryMailPacks(ByVal Username As String, ByVal

Password As String, ByVal ProductType As String, ByVal SearchText As
String, ByVal ListFormat As String, ByVal FailureResultFormat As String) As
String

This call retrieves a list of library mail packs.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
ProductType String Specify as “A4Letter”, “BusinessCard”, “GreetingCard”,
or “Postcard”. If not supplied then defaults as specified
in default mailing options. The product type must be
available for your account, for example business cards
are currently only available for corporate accounts,
please see the Docmail website to confirm the products
available.
SearchText String(100) Search the mail pack names using the supplied search
text.
PageSize Integer Specify the number of results per page, must be
between 1 and 50.
PageNumber Integer The page of results to return. Use the List Library Mail
Packs Page Count call to return how many pages are
available.
SortColumn String Specify one of the returned columns, see the list below.
Defaults to “Mail pack name” if not supplied.
SortDescending Boolean Sort the specified sort column descending.
ListFormat String Specify as “CSV” or XML see List Formats.
FailureReturnFormat String Specify as “Text” or “XML” see Return Formats.

This call returns the following columns of data ordered by mail pack name and
created on date:

Column header Data type Description

Mail pack name String The mail pack name.
Number of templates Integer The number of templates on the mail pack.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 43
List Library Mail Packs Page Count

Public Function ListLibraryMailPacks(ByVal MailingPresentationGroup As

String, ByVal ProductType As String, ByVal SearchText As String, ByVal
PageSize As Integer, ByVal PageNumber As Integer, ByVal SortColumn As
String, ByVal SortDescending As Boolean, ByVal ListFormat As String, ByVal
FailureReturnFormat As String) As String

This call retrieves the page count for a list of library mail packs, returns a page count
of zero if no mail packs are found for the search criteria.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
ProductType String Specify as “A4Letter”, “BusinessCard”, “GreetingCard”,
or “Postcard”. If not supplied then defaults as specified
in default mailing options. The product type must be
available for your account, for example business cards
are currently only available for corporate accounts,
please see the Docmail website to confirm the products
available.
SearchText String(100) Search the mail pack names using the supplied search
text.
PageSize Integer Specify the number of results per page, must be
between 1 and 50.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 44
List Library Mailing Lists

Public Function ListLibraryMailingLists(ByVal MailingPresentationGroup As

String, ByVal SearchText As String, ByVal PageSize As Integer, ByVal
PageNumber As Integer, ByVal SortColumn As String, ByVal SortDescending As
Boolean, ByVal ListFormat As String, ByVal FailureReturnFormat As String)
As String

This call retrieves a list of library mailing lists.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
SearchText String(100) Search the mailing list names using the supplied search
text.
PageSize Integer Specify the number of results per page, must be
between 1 and 50.
PageNumber Integer The page of results to return. Use the List Library
Mailing Lists Page Count call to return how many pages
are available.
SortColumn String Specify one of the returned columns, see the list below.
Defaults to “Mail pack name” if not supplied.
SortDescending Boolean Sort the specified sort column descending.
ListFormat String Specify as “CSV” or XML see List Formats.
FailureReturnFormat String Specify as “Text” or “XML” see Return Formats.

This call returns the following columns of data ordered by mail pack name and
created on date:

Column header Data type Description

Mailing list name String The mail pack name.
Number of addresses Integer The number of addresses on the mailing list.

List Library Mailing Lists Page Count

Public Function ListLibraryMailingListsPageCount(ByVal

MailingPresentationGroup As String, ByVal SearchText As String, ByVal
PageSize As Integer, ByVal ReturnFormat As String) As String

This call retrieves the page count for a list of library mailing lists, returns a page count
of zero if no mailing lists are found for the search criteria.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
SearchText String(100) Search the mailing list names using the supplied search
text.
PageSize Integer Specify the number of results per page, must be
between 1 and 50.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 45
List Mailing Filter Categories

Public Function ListMailingFilterCategories(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal ListFormat As
String, ByVal FailureResultFormat As String) As String

This call is for corporate users only and returns a list of the mailing filter categories.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID to get the categories for.
ListFormat String Specify as “CSV” or XML see List Formats.
FailureReturnFormat String Specify as “Text” or “XML” see Return Formats.

This call returns the following columns of data ordered Category name:

Column header Data type Description

Category name String The mail pack name.

List Mailing Filters For Category

Public Function ListMailingFiltersForCategory(ByVal Username As String,

ByVal Password As String, ByVal MailingGUID As System.Guid, ByVal
CategoryName As String, ByVal ListFormat As String, ByVal
FailureResultFormat As String) As String

This call is for corporate users only and returns a list of mailing filter values for a
given category.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID to get the filters for.
CategoryName String(50) The category to return a list for.
ListFormat String Specify as “CSV” or XML see List Formats.
FailureReturnFormat String Specify as “Text” or “XML” see Return Formats.

This call returns the following columns of data ordered Category name:

Column header Data type Description

Mailing filter String The mailing filter name.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 46
List Mailing Variable Values

Public Function ListMailingVariableValues(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal TemplateGUID As
System.Guid, ByVal VariableName As String, ByVal ListFormat As String,
ByVal FailureResultFormat As String) As String

This call is for corporate users only and returns a list of variable values for a given
mailing template GUID and variable name.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
TemplateGUID GUID The template GUID on the mailing.
VariableName String(50) The name of the variable.
ListFormat String Specify as “CSV” or XML see List Formats.
FailureReturnFormat String Specify as “Text” or “XML” see Return Formats.

This call returns the following columns of data ordered Category name:

Column header Data type Description

Variable value String The variable value option.

List Product Types

Public Function ListProductTypes(ByVal Username As String, ByVal Password

As String, ByVal ListFormat As String, ByVal FailureReturnFormat As String)
As String

This call returns a list of available product types.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
ListFormat String Specify as “CSV” or XML see List Formats.
FailureReturnFormat String Specify as “Text” or “XML” see Return Formats.

This call returns the following columns of data ordered product description:

Column header Data type Description

Product name String The product name, as used when passing to other
calls in the API.
Product description String The product description, a friendly display name for the
product.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 47
List Document Types

Public Function ListDocumentTypes(ByVal Username As String, ByVal Password

As String, ByVal ProductType As String, ByVal ListFormat As String, ByVal
FailureReturnFormat As String) As String

This call returns a list of available document types for a given product type.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
ProductType String Specify as “A4Letter”, “BusinessCard”, “GreetingCard”,
or “Postcard”. If not supplied then defaults as specified
in default mailing options. The product type must be
available for your account, for example business cards
are currently only available for corporate accounts,
please see the Docmail website to confirm the products
available.
ListFormat String Specify as “CSV” or XML see List Formats.
FailureReturnFormat String Specify as “Text” or “XML” see Return Formats.

This call returns the following columns of data ordered by document type description:

Column header Data type Description

Document type String The document type, as used when passing to other
calls in the API.
Document type description String The document type description, a friendly display
name for the document type.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 48
List Template Variables

Public Function ListTemplateVariables(ByVal Username As String, ByVal

Password As String, ByVal TemplateGUID As System.Guid, ByVal
RequiresEntryOnly As Boolean, ByVal ListFormat As String, ByVal
FailureReturnFormat As String) As String

This call returns a list of available template variables for a given template. Please
note that before using this call for mailing templates a partial Process Mailing call
must be made to process the template. Additionally if custom address data is being
used then the mailing list must also have been added, otherwise the variable types
for the custom address fields will be returned as “Free text” rather than “Custom
address tag”.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
TemplateGUID GUID The TemplateGUID to request the list of variables for.
RequiresEntryOnly Boolean Whether to return only variables that require values
entering. If false returns all tags found in the document.
ListFormat String Specify as “CSV” or XML see List Formats.
FailureReturnFormat String Specify as “Text” or “XML” see Return Formats.

This call returns the following columns of data, ordered as the variables are detected
in the file:

Column header Data type Description

Variable name String The variable name.
Variable type String The type of variable, e.g. "Free text", "Custom
address tag", "Address tag", "Production date", or
"Data property". For corporate accounts the type of
variables could also include "Organisational
structure", "Selected paragraph", or "Selected
image".

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 49
7 - Zip Data

The referenced calls in this section can be used to download a zip file of the mail
pack or mailing list data.

Get Mail Pack Zip

Public Function GetMailPackZip(ByVal Username As String, ByVal Password As

String, ByVal MailingGUID As System.Guid, ByVal FailureReturnFormat As
String) As Byte()

This call provides all the templates from a mail pack in a zip archive file.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing to return the mail pack for.
FailureReturnFormat String Specify as “Text” or “XML” see Return Formats.

Get Mailing List Zip

Public Function GetMailingListZip(ByVal Username As String, ByVal Password

As String, ByVal MailingGUID As System.Guid, ByVal FailureReturnFormat As
String) As Byte()

This call provides a zip archive file containing a CSV file of the addresses on a
submitted mailing.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing to return the mailing list for.
FailureReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 50
8 - Account and User Administration

The referenced calls in this section can be used to add accounts or users to Docmail.

Create Account

Public Function CreateAccount(ByVal Username As String, ByVal Password As

String, ByVal AccountName As String, ByVal LoginUserID As String, ByVal
LoginUserIDPassword As String, ByVal Title As String, ByVal FirstName As
String, ByVal Surname As String, ByVal JobTitle As String, ByVal Telephone
As String, ByVal Address As String, ByVal EmailAddress As String, ByVal
AllowWebServiceAccess As Boolean, ByVal ReferredBy As String, ByVal
HowDidYouFindUs As String, ByVal ReturnFormat As String) As String

This call creates a Docmail account. You must obtain permission from the Docmail
support team to use this call.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
AccountName String(70) A name for the account.
LoginUserID String(30) The user name for the master user on the account.
LgoinUserIDPassword String(30) The password for the master user on the account. Must
be at least 6 characters long and must not be the same
as the LoginUserID.
Title String(15) The title for the account and master user, e.g. Mr, Mrs
etc.
FirstName String(30) The first name for account and master user.
Surname String(30) The surname for the account and master user.
JobTitle String(60) The job title for the account and master user.
Telephone String(50) The telephone number for the account and master user.
Address String(50 * 6) The account and master user address. Limited to 50
characters per line, up to 6 lines.
EmailAddress String(70) The email address for the account and master user.
AllowWebServiceAccess Boolean Allow this user to place automated orders via a web
service.
ReferredBy String(100) Set to an account number for referral commission.
HowDidYouFindUs String(100) How did the user find our about Docmail.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 51
Add User

Public Function AddUser(ByVal Username As String, ByVal Password As String,

ByVal LoginUserID As String, ByVal LoginUserIDPassword As String, ByVal
Title As String, ByVal FirstName As String, ByVal Surname As String, ByVal
JobTitle As String, ByVal Telephone As String, ByVal Address As String,
ByVal EmailAddress As String, ByVal AllowWebServiceAccess As Boolean, ByVal
AccountDataAdministrator As Boolean, ByVal ApprovingAdministrator As
Boolean, ByVal CanSpendCredit As Boolean, ByVal AccountRole As String,
ByVal DefaultMailingsToAdvanceMode As Boolean, ByVal DoNotSendEmails As
Boolean, ByVal ReturnFormat As String) As String

This call adds a user to your account.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name for the account the user is being
added to.
Password String(30) Password for the user.
LoginUserID String(30) The user name for the user being added.
LgoinUserIDPassword String(30) The password for the user being added. Must be at
least 6 characters long and must not be the same as the
LoginUserID.
Title String(15) The title for the new user, e.g. Mr, Mrs etc.
FirstName String(30) The first name for the new user.
Surname String(30) The surname for the new user.
JobTitle String(60) The job title for the new user.
Telephone String(50) The telephone number for the new user.
Address String(50 * 6) The address for the new user. Limited to 50 characters
per line, up to 6 lines.
EmailAddress String(70) The email address for the new user.
AllowWebServiceAccess Boolean Allow this user to place automated orders via a web
service?
AccountDataAdministrator Boolean Can the user administrate all the account data?
ApprovingAdministrator Boolean Can the user approve all mailings?
CanSpendCredit Boolean Can the user spend top-up credit?
AccountRole String(50) Corporate users only, specify the name of an account
role.
DefaultMailings Boolean Should mailings in the web site default to using advance
ToAdvanceMode mode?
DoNotSendEmails Boolean Exclude the user from Docmail emails?
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 52
Add User Organisation Structure Link

Public Function AddUserOrganisationStructureLink(ByVal Username As String,

ByVal Password As String, ByVal LinkUserName As String, ByVal
OrganisationStructureLevel As String, ByVal OrganisationStructureValue As
String, ByVal ReturnFormat As String) As String

This call is for corporate users only and links a user to the organisational structure.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name for the account that the link is
required on.
Password String(30) Password for the user.
LinkUserName String(30) The username to link to the organisational structure.
OrganisationStructureLevel String(50) The structural level defined in the organisation
structure, e.g. Company, Department etc.
OrganisationStructureValue String The value of the structure level to add.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Add User Sign-up Data

Public Function AddUserSignupData(ByVal Username As String, ByVal Password

As String, ByVal SignUpHeader As String, ByVal SignUpValue As String, ByVal
ReturnFormat As String) As String

This call is for corporate users only and adds additional sign-up data for the user.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
SignUpHeader String The header name for the sign-up data.
SignUpValue String The value of the sign-up data for the user.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 53
9 - Mailing List Address Counts and Price Estimates

The referenced calls in this section are designed to obtain price estimates. The
address count calls can be used to obtain counts of addresses that can then be
passed to the price estimate call.

Add Mailing List File For Address Count

Public Function AddMailingListFileForAddressCount(ByVal Username As String,

ByVal Password As String, ByVal FileName As String, ByVal MailingListData
As Byte(),ByVal DataFormat As String, ByVal HasHeaders As Boolean, ByVal
SheetName As String, ByVal MappingDelimiter As String, ByVal
MappingFixedWidthChars As String, ByVal MappingName As String, ByVal
ReturnFormat As String) As String

This function adds the addresses from a mailing list file to a temporary mailing list.
This call returns a Mailing List GUID that can be used for obtaining address count
information.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
FileName String(255) The file name must be in .csv, .txt, .xls, .xlsx or .xml
format.
FileData Byte Array The image file data.
DataFormat String Specify as "Excel", "CSV", "Tab separated",
"Delimited", or "Fixed width".
HasHeaders Boolean Does the file have a row specifying the headers?
SheetName String(31) For Excel data only, the Excel sheet name to import
from. If not supplied the first sheet in the Excel file will
be used.
MappingDelimiter String(10) For Delimited data only, the delimiter to use. If not
supplied then delimited files will be assumed to be tab
delimited.
MappingFixedWidthChars String For Fixed Width data only, a comma separated list of
the numbers of characters for each column.
MappingName String(50) The name of a library mapping to use.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 54
Add Mailing List String For Address Count

Public Function AddMailingListStringForAddressCount(ByVal Username As

String, ByVal Password As String, ByVal MailingListData As String,
ByVal DataFormat As String, ByVal HasHeaders As Boolean, ByVal SheetName As
String, ByVal MappingDelimiter As String, ByVal MappingFixedWidthChars As
String, ByVal MappingName As String, ByVal ReturnFormat As String) As
String

This function adds the addresses from a formatted string to a temporary mailing list.
This call returns a Mailing List GUID that can be used for obtaining address count
information.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingListData String A formatted string containing the data.
DataFormat String Specify as "Excel", "CSV", "Tab separated",
"Delimited", or "Fixed width".
HasHeaders Boolean Does the file have a row specifying the headers?
SheetName String(31) For Excel data only, the Excel sheet name to import
from. If not supplied the first sheet in the Excel file will
be used.
MappingDelimiter String(10) For Delimited data only, the delimiter to use. If not
supplied then delimited files will be assumed to be tab
delimited.
MappingFixedWidthChars String For Fixed Width data only, a comma separated list of
the numbers of characters for each column.
MappingName String(50) The name of a library mapping to use.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 55
Poll Mailing List For Address Count

Public Function PollMailingListAddressCounts(ByVal Username As String,

ByVal Password As String, ByVal MailingListGUID As System.Guid, ByVal
ReturnFormat As String) As String

This function polls the status of the address count.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingListGUID GUID The mailing list to return the address count for.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

This function returns the following data

Return key Description

Complete Has the address count completed.
Cheapest postal rate If complete only. Count of the addresses that qualify
for the cheapest postal rate.
Western Europe If complete only. Count of the addresses that are
classed as Western Europe
Rest of the world If complete only. Count of the addresses that are
classed as rest of the world.
Surcharge postage If complete only. Count of the addresses that will incur
a postal surcharge.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 56
Get Mailing Price Estimate

Public Function GetMailingPriceEstimate(ByVal Username As String, ByVal

Password As String, ByVal MailingGUID As System.Guid, ByVal TotalSides As
Integer, ByVal ReturnFormat As String) As String

This function gets a price estimate for a mailing given a total number of expected
printed sides.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing to get the price estimate for.
TotalSides Integer The number of sides expected.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 57
Get Price Estimate

Public Function GetPriceEstimate(ByVal Username As String, ByVal Password

As String, ByVal DocumentType As String, ByVal IsMono As Boolean, ByVal
IsDuplex As Boolean, ByVal DeliveryType As String, ByVal DiscountCode As
String, ByVal MinEnvelopeSize As String, ByVal EnvelopeGroup As String,
ByVal Copies As Integer, ByVal TotalSides As Integer, ByVal
StandardAddressCount As Integer, ByVal SurchargeAddressCount As Integer,
ByVal WesternEuropeAddressCount As Integer, ByVal
RestOfTheWorldAddressCount As Integer, ByVal ReturnFormat As String) As
String

This function gets a price estimate for a given set of parameters.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
DocumentType String Specify as “A4Letter”, “BusinessCard”,
“GreetingCardA5”, “PostcardA5”, “PostcardA6”,
“PostcardA5Right” or “PostcardA6Right”. Postcard A5
and A6 have a left side address panel; use the Right
variations for a right side address panel. The
document type must be available for your account, for
example business cards are currently only available for
corporate accounts, please see the Docmail website to
confirm the document types available.
IsMono Boolean Control if the mailing is printed in black and white (true)
or colour (false).
IsDuplex Boolean Control if the mailing is double sided (true) or single
sided (false).
DeliveryType String Specify as “First”, “Standard” or “Courier”. If not
supplied then defaults as specified in default mailing
options.
DiscountCode String(20) A discount code to apply to the mailing.
MinEnvelopeSize String Specify as “C4”, “C5” or leave blank.
EnvelopeGroup String For corporate users only, leave blank or supply
“Docmail” for all other users.
Copies Integer Defaults to 1, other value only available for products
that support copies, must match a value available on
the delivery address screen in the Docmail website.
TotalSides Integer The number of sides expected.
StandardAddressCount Integer The number of standard addresses.
SurchageAddressCount Integer The number of surcharge addresses.
WesternEurope Integer The number of western Europe addresses.
AddressCount
RestOfTheWorld Integer The number of rest of the world addresses.
AddressCount
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 58
10 - Adding Library Data

The referenced calls in this section can be used to add data to the Library in Docmail.

Add Mailing List File To Library

AddMailingListFileToLibrary(ByVal Username As String, ByVal Password As

String, ByVal MailingListName As String, ByVal FileName As String, ByVal
MailingListData As Byte(), ByVal FileType As String, ByVal HasHeaders As
Boolean, ByVal SheetName As String, ByVal MappingDelimiter As String, ByVal
MappingFixedWidthChars As String, ByVal MappingName As String, ByVal
ReturnFormat As String) As String

This function adds a mailing list file to a library mailing list, creating the mailing list if it
does not already exist.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingListName String(50) The name of the mailing list.
FileName String(255) The file name must be in .csv, .txt, .xls, .xlsx or .xml
format.
FileData Byte Array The image file data.
DataFormat String Specify as "Excel", "CSV", "Tab separated",
"Delimited", or "Fixed width".
HasHeaders Boolean Does the file have a row specifying the headers?
SheetName String(31) For Excel data only, the Excel sheet name to import
from. If not supplied the first sheet in the Excel file will
be used.
MappingDelimiter String(10) For Delimited data only, the delimiter to use. If not
supplied then delimited files will be assumed to be tab
delimited.
MappingFixedWidthChars String For Fixed Width data only, a comma separated list of
the numbers of characters for each column.
MappingName String(50) The name of a library mapping to use.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 59
Add Mailing List String To Library

Public Function AddMailingListStringToLibrary(ByVal Username As String,

ByVal Password As String, ByVal MailingListName As String, ByVal
MailingListData As String, ByVal DataFormat As String, ByVal HasHeaders As
Boolean, ByVal SheetName As String, ByVal MappingDelimiter As String, ByVal
MappingFixedWidthChars As String, ByVal MappingName As String, ByVal
ReturnFormat As String) As String

This function adds the addresses from a formatted string to a library mailing list,
creating the mailing list if it does not already exist.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingListName String(50) The name of the mailing list.
MailingListData String A formatted string containing the data.
DataFormat String Specify as "Excel", "CSV", "Tab separated",
"Delimited", or "Fixed width".
HasHeaders Boolean Does the file have a row specifying the headers?
SheetName String(31) For Excel data only, the Excel sheet name to import
from. If not supplied the first sheet in the Excel file will
be used.
MappingDelimiter String(10) For Delimited data only, the delimiter to use. If not
supplied then delimited files will be assumed to be tab
delimited.
MappingFixedWidthChars String For Fixed Width data only, a comma separated list of
the numbers of characters for each column.
MappingName String(50) The name of a library mapping to use.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 60
Add Template File To Library

Public Function AddTemplateFileToLibrary(ByVal Username As String, ByVal

Password As String, ByVal TemplateName As String, ByVal FileName As String,
ByVal FileData As Byte(), ByVal DocumentType As String, ByVal
AddressedDocument As Boolean, ByVal AddressFontCode As String, ByVal
TemplateType As String, ByVal BackgroundName As String, ByVal
CanBeginOnBack As Boolean, ByVal NextTemplateCanBeginOnBack As Boolean,
ByVal ProtectedAreaPassword As String, ByVal EncryptionPassword As String,
ByVal BleedSupplied As Boolean, ByVal Copies As Integer, ByVal Instances As
Integer, ByVal InstancePageNumbers As String, ByVal CycleInstancesOnCopies
As Boolean, ByVal ReturnFormat As String) As String

This call adds a template document to the library, overwriting the existing background
of the same name if it already exists.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
Template Name String(50) A name to refer to the template by. Optional, defaults
to the file name if not supplied.
FileName String(255) The template file name, must be in .doc, .docx, .rtf or
.pdf format.
FileData Byte Array The template file data.
DocumentType String Specify as “A4Letter”, “BusinessCard”,
“GreetingCardA5”, “PostcardA5”, “PostcardA6”,
“PostcardA5Right” or “PostcardA6Right”. Postcard A5
and A6 have a left side address panel; use the Right
variations for a right side address panel. The
document type must be available for your account, for
example business cards are currently only available for
corporate accounts, please see the Docmail website to
confirm the document types available.
AddressedDocument Boolean Add the address panel to the document. The first
template uploaded onto a mail pack will be
automatically set as an addressed document.
AddressFontCode String Specify as "Arial 10", "Arial 11", "Arial 12", "Arial 13",
"Arial 14", "Courier 10", "Courier 11", "Courier 12",
"Courier 13", "Courier 14", "Gotham 9", "Gotham 10",
"Gotham 12", "Helvetica 12", "Helvetica 13", "Helvetica
14", "MetaOT 10", "MetaOT 11", "MetaOT 12",
"Trebuchet 10", "Trebuchet 11", "Trebuchet 12",
"Verdana 10", "Verdana 11", or "Verdana 12". Defaults
to “Arial 10”.
TemplateType String Specify as “Document” or “Preformatted Stream”.
Defaults to “Document”.
BackgroundName String(120) Optional name of a background to use from the library.
CanBeginOnBack Boolean For duplex printing only, can this template begin on the
back of another template?
NextTemplateBegin Boolean For duplex printing only, can another template begin on
CanBeginOnBack the back of this template?
ProtectedAreaPassword String(255) Password for protected areas in the document.
EncryptionPassword String(255) Password for an encrypted document.
BleedSupplied Boolean For products that support bleed only, has the bleed
been supplied?
Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 61
Copies Integer Defaults to 1, other value only available for products
that support copies, must match a value available on
the delivery address screen in the Docmail website.
Instances Integer The number of instances of a document within a PDF
file. Currently only available for fixed page document
formats.
InstancePageNumbers String Functionality not yet implemented. A comma
separated list of page numbers to identify the instances
for a non fixed page document format.
CycleInstancesOnCopies Boolean Only available for products that support copies, if true a
different instance is used for each copy.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Add Background File To Library

Public Function AddBackgroundFileToLibrary(ByVal Username As String, ByVal

Password As String, ByVal BackgroundName As String, ByVal DocumentType As
String, ByVal FileName As String, ByVal FileData As Byte(), ByVal
EncryptionPassword As String, ByVal ReturnFormat As String) As String

This call allows a background file to be added to the library, overwriting the existing
background of the same name if it already exists.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailingGUID GUID The mailing GUID returned from creating the mailing.
TemplateGUID GUID The template to add the background against.
Background name String(120) The name of the background, defaults to the file name
if not supplied.
FileName String(255) The background file name, must be in .doc, .docx, .rtf
or .pdf format.
FileData Byte Array The background file data.
EncryptionPassword String(255) Password for an encrypted document.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 62
Add Mail Pack To Library

Public Function AddMailPackToLibrary(ByVal Username As String, ByVal

Password As String, ByVal MailPackName As String, ByVal DocumentType As
String, ByVal ReturnFormat As String) As String

This call adds a mail pack to the library. Returns a mail pack GUID of either the
existing mail pack with the name supplied or a newly created mail pack if the name
does not exist.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailPackName String(50) The mail pack name.
DocumentType String Specify as “A4Letter”. There are currently no other
document types that support mail packs. The product
type must be available for your account, please see the
Docmail website to confirm the products available.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Add Template To Library Mail Pack

Public Function AddTemplateToLibraryMailPack(ByVal Username As String,

ByVal Password As String, ByVal MailPackName As String, ByVal TemplateName
As String, ByVal ReturnFormat As String) As String

This call adds a library template to a library mail pack.

Parameter Data Type / Description

Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MailPackName String(50) The mail pack name.
TemplateName String(50) The name of the template from the library. If there is
more than one template in the library with the same
name the template that was created first is used.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 63
11 - Extended Calls

This section is for calling additional functionality that may be made available as
standard calls in future versions of the API.

Extended Call

Public Function ExtendedCall(ByVal Username As String, ByVal Password As

String, ByVal MethodName As String, ByVal Properties As ExtendedProperty(),
ByVal ReturnFormat As String) As String

This call is for calling an extended method, see the http://www.cfhdocmail.com/API

for information on any available extended calls.

Parameter Data Type / Max Description

length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MethodName String(50) The method name, see the Docmail API website for
details of any extended method names available.
Properties ExtendedProperty A collection of extended properties. See the class
Collection definition below.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Extended property class definition:

Public Class ExtendedProperty
Public Property PropertyName() As String
Public Property PropertyValue() As Object
End Classe

Extended Call Definition

Public Function ExtendedCallDefinition(ByVal Username As String, ByVal

Password As String, ByVal MethodName As String, ByVal ReturnFormat As
String) As String

Get the definition for an extended method, returns each parameter name and the
data type for use with the ExtendedCall method.
Parameter Data Type / Description
Max length
Username String(30) Docmail user name.
Password String(30) Password for the user.
MethodName String(50) The method name, see the Docmail API website for
details of any extended method names available.
ReturnFormat String Specify as “Text” or “XML” see Return Formats.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 64
Error codes

The following error codes may be returned by Docmail:

Error Code ID Error Code Description

-1 ValidationError The validation of the data was unsuccessful.

-2 RecordNotFound A requested record could not be found.

-3 ConcurrencyError Data has been updated since the data was

loaded, preventing the save from being able to
be performed.
-4 NoRecordsAffected An update or deletion of data affected no
records; therefore the data may have already
been deleted or an incorrect reference may
have been supplied.
-5 UnexpectedError A general failure has occurred; the failure
message will include a unique error number for
tracking a problem through our support team.
-6 PermissionDenied The user specified does not have permission to
perform an operation.
-7 FileNotFound A file name was specified that does not exist in
the supplied data.
-8 SystemUnavailable The web service is currently unavailable due to
maintenance.
-21 PropertyValidationError The validation of the data in a particular
property was unsuccessful.
-22 PropertyRequired Data for a required property was not supplied.

-23 PropertyDataType Incorrect type of data was supplied.

-24 PropertyDataTypeLength The numeric property length was outside the

valid range.
-25 PropertyScale Too many decimal places after the decimal
point for the decimal property.
-26 PropertyPrecision Too many numbers in a decimal property.

-27 PropertyMaxLength The string property was over the maximum

length.
-101 InsufficentTopUpFunds There are insufficient funds in the account to
cover the cost of the order.
-102 DiscountExpired A specified discount code has expired.
-106 AccountActivationRequired The account has not been activated.
-108 ProofTotalPagesIncorrect The proof page total is incorrect for a fixed page
document type. For example if you supply a
document with 3 pages on a postcard order.
-109 InvalidXML The XML is invalid for the schema.
-110 EncryptedDocument A supplied document is encrypted and a valid
password has not been supplied.
-111 CorruptDocument A supplied document is corrupt.
-113 MaintenanceMode The system is currently unavailable for
maintenance.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 65
Example code

Adding a service reference or web reference in .NET

There are two options for referencing the web service, either using a service
reference or a web reference. The choice available will depend on your type of
project and version of .NET.

Service reference:
Right click on your project and select “Add Service Reference”.

Web reference:
Right click on your project and select “Add Web Reference”.

For live enter https://www.cfhdocmail.com/LiveAPI2/DMWS.asmx

For test enter https://www.cfhdocmail.com/TestAPI2/DMWS.asmx

Enter the namespace or web reference name as “DMWS” if you want to follow the
code examples.

Click OK or Add Reference to add the service reference or web reference to the
project.

Service Reference size limit

By default .NET 2005 and 2008 will limit the amount of information that can be
exchanged with the web service. In the binding section of the app.config or
web.config increase the message size as required, or set to a large default as shown
below:

maxBufferSize="2147483647" maxBufferPoolSize="2147483647"
maxReceivedMessageSize="2147483647"

maxStringContentLength="2147483647" maxArrayLength="2147483647"

Service Reference timeout limit

By default .NET 2005 and 2008 will limit the time of a connection to 1 minute. This is
sufficient for most operations, but for very large files this may need increasing in the
binding section of the app.config or web.config. The example below shows
increasing the timeout to 5 minutes for uploading and downloading:

receiveTimeout="00:05:00" sendTimeout="00:05:00"

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 66
VB .NET code Samples

Declaring the service reference in code:

Dim oService As New DMWS.DMWSSoapClient()

Declaring the web reference in code:

Dim oService As New DMWS.DMWS()

Code samples:

The following function convertes a text result string into a hash table for easy access
to the return data:
Private Function ResultHashTable(ByVal ResultData As String) As Hashtable
Dim oHashTable As New Hashtable
If Not ResultData = "" Then
For Each sLine As String In ResultData.Split(vbCrLf.ToCharArray)
If sLine <> "" Then
Dim iIndex As Integer = sLine.IndexOf(": ")
Dim sKey As String = sLine.Substring(0, iIndex)
Dim sData As String = sLine.Substring(iIndex + 2, sLine.Length -
iIndex - 2)

oHashTable.Add(sKey, sData)
End If
Next
End If
Return oHashTable
End Function

The following function opens a file as a byte array:

Private Function OpenFileAsByteArray(ByVal FilePath As String) As Byte()
Dim oFileStream As System.IO.FileStream =
System.IO.File.OpenRead(FilePath)
Dim iBytes As Integer = CType(oFileStream.Length, Integer)
Dim oByteArray(iBytes - 1) As Byte
oFileStream.Read(oByteArray, 0, iBytes)
oFileStream.Close()
Return oByteArray
End Function

The following sub routine saves a byte array to a file:

Private Sub SaveFromByteArray(ByVal FileData As Byte(), ByVal FilePath As
String)
Using oFileStream As New System.IO.FileStream(FilePath,
System.IO.FileMode.Create)
oFileStream.Write(FileData, 0, FileData.Length)
oFileStream.Close()
End Using
End Sub

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 67
The following code places a mailing using a zip file that contains a configuration file
and any related template and mailing list files:
' Place the mailing
Dim oResultHash As Hashtable =
ResultHashTable(oService.CreateFileMailing("[Username]", "[Password]",
OpenFileAsByteArray("C:\Temp\Mailing.zip"), "Text"))

' Capture the mailing GUID

Dim gMailingGUID As New System.Guid(CStr(oResultHash("MailingGUID")))

The following code creates a mailing:

' Create a mailing

Dim oResultHash As Hashtable =
ResultHashTable(oService.CreateMailing("[Username]", "[Password]",
"[Application Name]", "A4Letter", "[Mailing Name]", "[Mailing
Description]", False, False, "Standard", False, True, Nothing, "", "Full
Name", "", "C5", "Text"))

' Capture the mailing GUID

Dim gMailingGUID As New System.Guid(CStr(oResultHash("MailingGUID")))

The following code adds a template file to a mailing:

' Add a template
oResultHash = ResultHashTable(oService.AddTemplateFile("[Username]",
"[Password]", gMailingGUID, "[Template Name]", "Template.doc",
OpenFileAsByteArray("C:\Temp\Template.doc"), "A4Letter", True, "Arial 10",
"Document", "", False, False, "", "", False, 1, 1, "", False, "Text"))

' Capture the template GUID

Dim gTemplateGUID As New System.Guid(CStr(oResultHash("TemplateGUID")))

The following code adds a mailing list file to a mailing:

' Add a mailing list
oResultHash = ResultHashTable(oService.AddMailingListFile("[Username]",
"[Password]", gMailingGUID, "MailingList.csv",
OpenFileAsByteArray("C:\Temp\MailingList.csv"), "CSV", True, "", "", "",
"", "Text"))

' Capture the mailing list GUID

Dim gMailingListGUID As New
System.Guid(CStr(oResultHash("MailingListGUID")))

The following code submits a mailing for processing:

oResultHash = ResultHashTable(oService.ProcessMailing("[Username]",
"[Password]", gMailingGUID, True, False, 0, "", "Topup", False, "[Email
address]", "[Email address]", "", "", "Text"))

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 68
The following code checks the status, looping until the proof is ready and then saves
the proof file to disk:
' Poll the mailing status.
Do
oResultHash = ResultHashTable(oService.GetStatus("[Username]",
"[Password]", gMailingGUID, "Text"))

Select Case CStr(oResultHash("Status"))

Case "Error in processing"

' Error trapping code add here ...
Exit Do

Case "Mailing submitted", "Mailing processed", "Partial processing

complete"
' Save the file to disk
SaveFromByteArray(oService.GetProofFile("[Username]",
"[Password]", gMailingGUID, "Text"), "C:\Temp\Proof.pdf")
Exit Do

End Select

' Wait one second between each poll

Threading.Thread.Sleep(1000)
Loop

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 69
Glossary of terms

Address
The data relating to an individual person in the mailing. This includes
their name, address and any additional information to be merged in a
Template.

Background
A background is a PDF file that appears behind text entered in a main
document, for example a letter head.

Default Mailing Options

The default options for a mailing, as configured in the Docmail Website.
To change the default options go to the Admin section and from the
Account box select the Default Mailing Options link.

Mailing
One of more templates that require sending to one or more addresses.
Mailings may also be referred to as orders.

Mailing List
The list of addresses that will receive the Mail Pack. A mailing list can be
saved via the Docmail website to be used over and over again.

Mail Pack
The collection of templates that are to be used in the mailing. Think of a
mail pack as a paperclip, holding different templates that you may want to
use together. Each mail pack will therefore always contain at least one
template, and possibly more. A mail pack can be saved via the Docmail
website to be used over and over again.

Template
A document file that will be sent to the mailing list. The document may
contain tags, e.g. <<FirstName>>, that can be replaced with either
address data or fixed variable data to produce the final output document.

Variable
A customisable tag in the template document that can be replaced with
either address data or fixed data. Fixed data will be the same text for all
recipients, for example <<SpecialOffers>>, could become “Spring Special
Offers”, or “Summer Special Offers”. Variables can be used for single
words or whole paragraphs of text.

Docmail Web Service v2.0 © 2011 CFH Total Document Management Ltd
Page 70