The API is provided through an HTTP REST web service with custom HTTP authentication (which means that simply a pair of username and password needs to be provided in the HTTP header in order to perform authentication). The URL to which the web service listens is http://<servername>:<port>/MailAndDeploy/Api.
The web service supports both POST and GET requests. POST requests need to supply their parameters in the HTTP message, GET requests may supply their parameters through URL parameters. For every request, the API will return an XML document that contains the requested data or, if unsuccessful, an error message.
GET Requests
As previously stated, GET requests need to supply their parameters by using query string parameters. An example for a GET request might be:
http://<servername>:<port>/MailAndDeploy/Api/?RequestType=CreateReportDocument&RepositoryN ame=CrmReporting&ReportName=CustomerReport&FileType=AdobePdfDocument&Parameter_Custo merId=1
This would instruct Mail & Deploy to process a CreateReportDocument request (see Create Report Document Request) by creating a report document from the Report CustomerReport in repository CrmReporting. The file type in which to create the report document is AdobePdfDocument and the ID of the customer for which to create that report is 1.
POST Requests
As previously stated, POST requests need to supply their parameters as part of the message header. POST requests need to be submitted to the URL http://<servername>:<port>/MailAndDeploy/Api.
Responses
Every request will be answered by Mail & Deploy API with an XML document.
Success Responses
If the request can be handled successfully by Mail & Deploy, an XML document that contains the return value for that request will be returned; the actual content of that XML document depends on the type of request; therefore, you will find detailed information about how success responses look like in the documentation of each individual request below.
Exception Responses
The XML document that will be returned in case the request fails is formatted as follows:
| <?xml version="1.0" encoding="utf-8"?> <MailAndDeployApiResponse Success="False" ExceptionMessage="{exception_message}" ExceptionStackTrace="{exception_stacktrace}" /> |
The following properties are contained in the response:
| Success | The value False indicates that the request has failed. |
| ExceptionMessage | An exception message that contains information about why the request has failed. |
| ExceptionStackTrace | Contains information about the stack trace of the exception. |
Reference
This reference provides information on all request types that can be made through Mail & Deploy API.
Create Report Document Request
This request instructs Mail & Deploy to create a report document from a report with a given file type and optionally parameters. The parameters for this request are:
| RequestType | This parameter specifies the type of request and needs to be set to CreateReportDocument. |
| RepositoryName | The name of the repository (see Repository) to which the report from which you want to create a report document belongs. |
| ReportName | The name of the report (see Reports) from which you want to create a report document. |
| File Type | The file type in which you want to create the report document. The range of available file types depends on the report type ( see Report Types). The following values can be provided:
|
| Parameter_* | You can supply values for report parameters (see Report Parameters) if the report from which you want to create a report document supports them. Each report parameter needs to be called Parameter_<name_of_report_parameter>. |
Example
The following URL can be used as a GET request to request a report document from a report named CustomerReport that is contained in a repository named CRMReports. The file type in which the report document shall be created is an Adobe PDF Document. The report contains three report parameters (see Report Parameters): CustomerId which represents the ID of the customer for which to create the report document, Year which defines the year for which the report document shall contain data and Month that defines the month for which the report document shall contain data:
http://<servername>:<port>/MailAndDeploy/Api/?RequestType=CreateReportDocument&RepositoryN ame=CRMReports&ReportName=CustomerReport&FileType=AdobePdfDocument&Parameter_Custome rId=1&Parameter_Year=2017&Parameter_Month=1
Success Response
The XML document that will be returned in case the request completes successfully is formatted as follows:
| <?xml version="1.0" encoding="utf-8"?> <MailAndDeployApiResponse Success="True" FileType="{file_type}" ReportDocumentContent="{base64_content}" /> |
The following properties are contained in the response:
Execute Task Request
his request instructs Mail & Deploy to execute a task (see Tasks) of the given repository. The parameters for this request are:
| RequestType | This parameter specifies the type of request and needs to be set to ExecuteTask. |
| RepositoryName | The name of the repository (see Repository) to which the task to execute belongs. |
| TaskName | The name of the task (see Tasks) you want to execute. |
| Parameter_* | You can supply values for task parameters (see Task Parameters) if the task you want to execute supports them. Each task parameter needs to be called Parameter_<name_of_task_parameter>. |
Example
The following URL can be used as a GET request to request the execution of the task named CreateStoreReports that is contained in a repository named CRMReports. The task contains three task parameters (see Task Parameters): StoreId which represents the IDs of the stores for which to execute the task, Year which defines the year for which to execute the task and Month that defines the month for which to execute the task:
http://<servername>:<port>/MailAndDeploy/Api/?RequestType=ExecuteTask&RepositoryName=CRMR eports&TaskName=CreateStoreReports &Parameter_StoreId=1|2|3&Parameter_Year=2017&Parameter_Month=1
Success Response
The XML document that will be returned in case the request completes successfully is formatted as follows:
| <?xml version="1.0" encoding="utf-8"?> <MailAndDeployApiResponse Success="True" /> |
The following properties are contained in the response:
| Success | The value True indicates that the request has completed successfully. |
Get Available Reports Request
This request instructs Mail & Deploy to return all available reports (see Reports) of the given repository. The parameters for this request are:
| RequestType | This parameter specifies the type of request and needs to be set to GetAvailableReports. |
| RepositoryName | The name of the repository (see Repository) for which to return all available reports. |
Example
The following URL can be used as a GET request to request all available reports of a repository named CRMReports:
http://<servername>:<port>/MailAndDeploy/Api/?RequestType=GetAvailableReports&RepositoryNam e=CRMReports
Success Response
The XML document that will be returned in case the request completes successfully is formatted as follows:
| <?xml version="1.0" encoding="utf-8"?> <MailAndDeployApiResponse Success="True"> <Report Name="{report_name}" Description="{report_description}"> <SupportedFileType Value="{supported_file_type}" /> ... <ReportParameter Name="{reportparameter_name}" Caption="{reportparameter_caption}" /> ... </Report> ... </MailAndDeployApiResponse> |
The following properties are contained in the response:
| Success | The value True indicates that the request has completed successfully. |
| ReportName | The name of the report. |
| Report Description | The description of the report. |
| Supported File Types | A list of file types supported by that report (i.e. report documents can be created in any of these supported file types). The following values are possible:
|
| Report Parameters | A list of zero or more report parameters (see Report Parameters) of that report. |
Get Available Tasks Request
This request instructs Mail & Deploy to return all available tasks (see Tasks) of the given repository. The parameters for this request are:
| RequestType | This parameter specifies the type of request and needs to be set to GetAvailableTasks. |
| RepositoryName | The name of the repository (see Repository) for which to return all available tasks. |
Example
The following URL can be used as a GET request to request all available reports of a repository named CRMReports:
http://<servername>:<port>/MailAndDeploy/Api/?RequestType=GetAvailableTasks&RepositoryName= CRMReports
Success Response
The XML document that will be returned in case the request completes successfully is formatted as follows:
| <?xml version="1.0" encoding="utf-8"?> <MailAndDeployApiResponse Success="True"> <Task Name="{report_name}" Description="{report_description}"> <TaskParameter Name="{taskparameter_name}" Caption="{taskparameter_caption}" /> ... </Task> ... </MailAndDeployApiResponse> |
The following properties are contained in the response:
| Success | The value True indicates that the request has completed successfully. |
| Task Name | The name of the task. |
| Task Description | The description of the task. |
| Task Parameters | A list of zero or more task parameters (see Task Parameters) of that task. |