Help center

View helpful articles, tutorials and FAQs on the set-up and configuration

of the FocalScope omnichannel suite, according to best practice.

Query emails by ticket number or folder using SOAP APIs

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)

Let us help

If you have any questions, or need further support, please don’t hesitate to reach out.