How to query emails by ticket number and by folder using SOAP API calls
Monday, December 5, 2016 3:36 AM

This article demonstrates how to use the 'QueryEmailsByTicketNumbers' and 'QueryEmailsByFolders' SOAP API functions and also provides a C# code sample to demonstrate implementation.


Querying emails by ticket number / by folder with a SOAP call

To use SOAP to query emails in FocalScope by ticket number, do the following:

  1. In the [Main menu], select [Screen > Administration]
  2. Select the [Advanced properties] tab
  3. Select the [External API > SOAP API] folder
  4. Click the [Obtain] button to generate a security token. 
    1. Copy the [Security token], you will need to to run the 'CloseTicket' function
  5. Click the [Open] button to launch the SOAP API test page
  6. Click the [QueryEmailsByTicketNumbers] link to run the function
  7. The 'QueryEmailsByTicketNumbers(secToken, rgTicket, fOnlyTicketRoot)' function uses the following parameters:
    1. string fOnlyTicketRoot - flag indicating email level in the ticket. Can be: False, true, 0, 1 
    2. string[] rgTicket - array comprising of ticket numbers
  8. The 'QueryEmailsByFolders(secToken, rgFolder, fOnlyTicketRoot, DateFrom, DateTo, DataLimit, PageNo)' function uses the following parameters:
    1. string[] rgFolder - array of folder names, e.g., Root's Folders/Incoming
    2. string DateFrom, DateTo - the interval of email received dates with the following format: YYYY-MM-DD HH:MM:SSPlease noteThe range can not exceed 1 month
    3. string DataLimit - amount of rows per page, e.g., 1000
    4. string PageNo - page number, begins from 1, e.g., 1

Please note: Parameter values for the 'QueryEmailsByTicketNumbers' and 'QueryEmailsByFolders' functions must match the above examples precisely. Also, the security token is mandatory and must not have expired.

Figure 1 - ...

Sample code

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Data;
using System.Data.SqlClient;
using System.Xml;

namespace ConsoleSoapClient
    class Program
        static SoapService.SoapApi soapService;

        static void QueryEmailsByTicketNumbers(string secToken, string fileName)
            string[] rgTicket = {"1589","10079","7185","8513","17218","1543" };
            string fOnlyTicketRoot = "true";

            DataSet ds = new DataSet();
            ds = soapService.QueryEmailsByTicketNumbers(secToken, rgTicket, fOnlyTicketRoot);

            XmlTextWriter writer = new XmlTextWriter(fileName, null);
            writer.Formatting = Formatting.Indented;


        static void QueryEmailsByFolders(string secToken, string fileName)
            string[] rgFolder = { "Shared Items/Ticketboxes/2.4 Other PCR" };
            string fOnlyTicketRoot = "0";
            string DateFrom = "2013-12-01";
            string DateTo = "2013-12-20";
            string DataLimit = "100";
            string PageNo = "3";

            DataSet ds = new DataSet();
            ds = soapService.QueryEmailsByFolders(secToken, rgFolder, fOnlyTicketRoot, DateFrom, DateTo, DataLimit, PageNo);

            XmlTextWriter writer = new XmlTextWriter(fileName, null);
            writer.Formatting = Formatting.Indented;


        static void Main(string[] args)
            soapService = new SoapService.SoapApi();

            soapService.Url = "http://localhost/emm/net/soapapi.asmx";

            string secToken = "6710ebc2da8754782f1e14ab8b6c7be5";

            QueryEmailsByTicketNumbers(secToken, "EmailsByTickets.xml");
            QueryEmailsByFolders(secToken, "EmailsByFolders.xml");

Additional Information

  • How to use FocalScope categories as custom fields and retrieve the associated tickets using SOAP API
  • Please noteIn cases where emails contain binary data, please use the QueryEmailsByTicketNumbersBase64 / QueryEmailsByFoldersBase64 functions (see attached file below). This way, the email body data you retrieve via the SOAP query will be encoded in Base64, and you will need to decode it
  • To include information about the number of attachments an email has, please use the QueryEmailsWithAttachInfoByTicketNumbersBase64 / QueryEmailsWithAttachInfoByFoldersBase64 functions. To retrieve the attachment(s) of  an email, please use the GetEmailAttachmentsByEmails function (see attached file below)