How to use the Remote Sendmail API
Monday, December 5, 2016 3:21 AM

The Remote Sendmail API allows you to set up a web form and collect emails from visitors to your website. This feature generates incoming / outgoing / post-to folder emails from web-form submissions, such as feedback, general / support enquiries, and contact us forms, and sends them to FocalScope. You can also have FocalScope dispatch emails when web forms are submitted. This can be done by by specifying outgoing in the email type parameter of the API. This article details how you can configure the Remote Sendmail API and generate links for use in application development and on your website.

Tutorial

Configuring the Remote Sendmail API

  1. In the [Main menu], select [Screen > Administration]
  2. Click the [Advanced properties] tab
  3. Navigate to the [External API > Remote Sendmail] folder
  4. In the right-hand pane, click the [...] button (highlighted in red) for the [Default folder] field
  5. In the [Select Folder] webpage dialog that appears, specify the ticketbox (personal or shared) that will be used to handle the emails generated by the Remote Sendmail web form
    1. Click [OK] to associate the selected ticketbox with the Remote Sendmail API
  6. Please note: Set the [Output format] to XML
  7. Click the [...] button for the [Security token] field (highlighted in blue)
  8. Continued in next section...

Figure 1 - Remote Sendmail settings



  1. In the [Security token] window, start by setting the expiry date in the [Expires] field. Please note: It is advisable to always set an expiry date for the Remote Sendmail web form
  2. In the [Use at most] field, you can specify the maximum number of times the web form can be used before it expires, leave the field blank to switch off the constraint
  3. Rest of fields are maintained automatically, please leave them to their default values


Figure 2 - Security token settings


Generating the Remote Sendmail link

  1. After you have configured the Remote Sendmail API, click the [Generate Link] button. Please note: The link generated is the actual API itself (highlighted in green). This link is intended for applications (and developers) to submit HTTP POST requests to the API
  2. Additionally, the [Test Link] button allows you to test the by using the web form linked to the [Test Link] button
  3. Optionally, web designers can get the basic HTML web form, which they can then style using CSS and embed in a website. Visitors can then create emails in FocalScope using the web form



Figure 3 - The API link

Generating and saving the Remote Sendmail HTML web form

  1. Click the [Test Link] button (see Figure 3)
  2. In the [Remote sendmail] test form, compose a test email by filling out the relevant fields.
    1. You can specify the body of the email as either text or a file. To select the file for the email body, click the [Browse] button and locate the file on your computer
    2. Define the [Email Type] by selecting it from the drop-down list. Options are: Outgoing, Incoming, Post-to-folder, and DraftPlease note: When the [Email Type] is set to Outgoing, the associated ticketbox must have an active SMTP account configured--this is to dispatch the email once it is received from the Remote Sendmail web form
    3. Optionally, add an attachment by clicking the [Add File] button and locating the file on your computer
    4. Optionally, a ticket number can be entered into the [Ticket #] field to automatically link the message to an existing ticket in the default folder configured for the Remote Sendmail API. Please note: If the ticket number entered does not match an existing ticket in the default folder, then an error will result upon submission
    5. Click [Submit] to generate the email. Within moments, you should receive the test email in the corresponding FocalScope ticketbox. If the email type was set to outgoing, you should verify that it has successfully been sent to the recipient(s)
  3. If the email test was successful, click the [Get HTML] button to copy the Remote Sendmail web form code to your system's clipboard. You will receive a popup notification if this is successful
  4. Continued in next section...

Figure 4 - The Remote Sendmail test form



  1. If you are not satisfied with the default form, you can click the [Edit HTML] button in Figure 4 and edit the form to match your needs
  2. Once you are done editing the form, copy the source code by clicking the [Get HTML code of the form] button (highlighted in blue)
  3. Continued in next section...


Figure 5 - Editing the Remote Sendmail form


  1. Create a new .txt file on your desktop, open it in Notepad, and press Ctrl+V to paste the web form HTML code in the system clipboard to the file.
  2. Save and close the .txt file
  3. Rename the .txt file and change the file extension to .html
  4. Open the newly renamed .html file in a web browser. You should see the Remote Sendmail web form, just as it appeared in the [Remote Sendmail] test form
  5. Please note: You can embed the Remote Sendmail web form into your website similar to how you embed the FocalScope Live Chat URL


Figure 6 - Remote Sendmail HTML web form


Accessing the output of the remote sendmail API

This section denotes the general flow and management of emails that are generated by the remote sendmail API.


  1. Whenever the sendmail form is used, the email is delivered to the FocalScope folder associated with the API
  2. Please note: Outgoing emails received from the API will also be sent out to the email addresses in the To, Cc, and Bcc fields. For this to happen, the associated sendmail folder must have a dedicated email account associated with it, otherwise outgoing emails will not be relayed to the intended recipients.



Figure 7 - Output from the remote sendmail API



Attachments
sendmaildemo.zip