Overview
TextAPI is commonly used with other software, such as electronic medical records software (EMR), to have two-way communication with FaxMaker for faxing and reporting the fax status back to the end-user through the EMR.
TextAPI is the only sending method in which the sender does not have to be a licensed user to send faxes. It also offers two options for transmission reports.
Information
Enabling TextAPI
To enable textAPI, follow the setting up textAPI article for information about enabling this feature.
Creating TextAPI Control Files
TextAPI control files require specific formatting which is covered in the Creating TextAPI Files article. These files can reference body files and attachments, specify coverpages, list recipients and fax numbers and other information listed in the referenced article.
TextAPI Response Files
TextAPI produces response files or transmission reports. Refer to step 4 under TextAPI flow for the specifics as well as the TextAPI Response file article. These files are can be used to tell users the status of the fax but are most commonly used to report back to a sending software so that software can read the response file and report and report the fax status via its interface to the end-user.
TextAPI Fax Flow
The fax flow is provided below for your reference, and it also helps in troubleshooting issues.
- The control file and any associated files are dropped into the TextAPI pickup folder specified in the FaxMaker Configuration.
- The FaxMaker Fax Server service picks up the files and processes them. This processing includes extracting the fax information from the control file and fax data.
- Once the files are processed, the fax data is converted to an image and transmitted via the fax device.
- The transmission report can work in one of the following two ways:
- If a licensed user has sent the fax, the transmission report is generated and dropped in the
FaxMaker\in
folder for the message transfer agent to send it to the user. - If no user is specified in the control file, a transmission report will not be generated. Instead, a response file will be created and dropped into the pickup folder, by default. If a user that is not a licensed user is specified in the control file, the fax will fail due to a user error.
This picture shows the flow of TextAPI fax information.
Reviewing TextAPI Faxes in Logging
In many cases, you can detect the sending method being used by the end-user by FaxMaker logging. You will see for the excerpts below we can tell what was in the control file from our logs and will usually not need to ask for a control file example unless it pertains to something specific, such as a wrong user or attachment. For textAPI the logs to review will be the following:
- faxserver.gfi_log.txt (called faxserver log in this article)
- textapi.gfi_log.txt (called textapi log in this article)
Each log will be covered below with text control file examples:
Scenario #1
The first control file will list only the fax number and the attachment to use.
In this file the ::1234 gives the number to call and the ::A=Test_Fax.pdf lists the attachment containing the fax data.
Reviewing the textapi log shows the number as the recipient and the attachment listed.
Finally, the faxserver displays the following information about the fax:
1 & 2: The .sfm file is named textapi.sfm
3. The user is noted as __Text_API__@FAXmaker
4. The fax number 1234 is the same as the textapi log and the text control file
5. The attachment text_fax.pdf is the file listed in the text control file as well as the textapi log.
Finally, we see the fax report being created for __Text_API__@FAXmaker, which is for a response file creation rather than an emailed transmission report.
Scenario #2
The next control file will contain the fax number, attachment as well as a FaxMaker licensed user. The user is shown as test1 which is the AD username. The full email address could be used as well.
The textapi log shows the same information::
The faxserver log is the same as scenario #1 except the user is shown. This fax is processed like a fax with a licensed user and gets a standard transmission report but still uses the textapi.sfm file association.