|
TReK ANSI-C
5.3.3
All ANSI-C APIs
|
The TReK email library provides ANSI C functions that configure the cURL open source software library, libcurl, to log into and send texts, email messages and email file attachments to a designated group of one or more recipients by communicating with an Simple Mail Transport Protocol (SMTP) email server. The TReK email library also provides the ability to create a dropbox that sends a file as a file attachment or sends the content of the file as a text or email message by moving the file to the dropbox. The library runs on both Windows 10 and Red Hat Enterprise Linux 7 operating systems.
Background
The TReK email library is dependent on libcurl, an open source client-side URL transfer library developed by the cURL project. The libcurl library provides C API functions that configure the library to programmatically establish a secure connection with an email server using a Transport Layer Security (TLS) version 1.3 socket prior to logging into an email account using an email account name and password.
The TReK email and text capability has been successfully tested with the Google Gmail server. It is recommended that users create a new Gmail account and use it to send emails and texts to designated recipients. The TReK software does not support retrieving emails from the user's Gmail account. When creating the Gmail account to send emails and texts you will need to configure your Gmail account to enable two-step verification and you will need to generate a Gmail App Password for TReK. You enable two-step verification by opening your Google account and selecting "Security" in the navigation panel. Under "Signing in to Google" select "2-Step Verification > Get started" and follow the on-screen steps. You create an app password by opening your Google account and selecting "Security" in the navigation panel. Under "Signing in to Google" select "App Passwords". On this page you may use "TReK" for the name of the application that will be using the password. Choose "Mail" under "Select app" and choose the appropriate device under "Select device" to select the application and device that will be using the app password. Choose "Generate" and follow the instructions to enter the app password. The app password is the 16-character code in the yellow bar on your device. After you generate your Gmail App password, simply use it instead of your current Google Gmail account password when sending emails or texts using a TReK application or library. TReK recommends only using the Gmail account to send emails and texts using the TReK software. TReK does not recommend using the account to receive emails.
TReK Email Library
Initialization:
The InitializeToolkitEmail or InitToolkitEmail function initializes the TReK email library by either providing email configuration parameters with the function call or by reading the email configuration parameters from a TReK email configuration file. An application should call the InitializeToolkitEmail or InitToolkitEmail function prior to using any of the TReK Email API functions. The format of a TReK email configuration file is a series of name value pairs that configure the library to meet user requirements. One or more spaces separate individual parameters on each line in the file. The following table identifies and describes the configuration file parameters.
| Email Configuration File Parameter | Description |
| log_messages_in_file | The log messages in file boolean controls message logging. If true, messages are recorded in a log file. The default value is false. |
| log_debug_messages | The log debug messages boolean controls logging debug messages. If true, debug messages are recorded in a log file. The default value is false. |
| log_file_path | The log file path is the absolute path to the directory where the log file should be written. If an empty string is provided, the default path is the user's home directory. |
| log_file_name | The log file name is the name to use for the log file. The default value "toolkit_email_log". |
| curl_debug_messages | Configure cURL to generate debug messages. If "true",cURL debug messages are produced. The default value is true. |
| verify_cert_authorities | Configure cURL to verify Certificate Authorities (CA) when establishing the TLS interface with the email server. The cURL website provides CA certificates extracted from Mozilla in Privacy-Enhanced Mail (PEM) format. The website provides a new CA file once every few months. Download the the CA PEM file (i.e., "cacert.pem") from http://curl.haxx.se/docs/caextract.html when configuring cURL to verify CAs. If "false", do not verify CAs. The default value is false. |
| ca_path_and_filename | The path and file name of the CA. The default value is "./cacert.pem". |
| smtp_server_address | Email SMTP server address. The default value is "smtp.gmail.com". |
| email_account_username | The username of the email account. |
| email_account_password | The password of the email account. TReK will not save the email account password in the configuration file. However, a user may add the password to the configuration file. |
| from_email_address | The email address that is being used to send emails and texts. |
| from_email_name | The email name that is included at the end of an email message. |
| Text Cell Phone Number Primitives | Associate a cell phone number with a cell phone carrier and optional group name and adds the information to a list of cell phone numbers using a "text_cell_phone_number" primitive. The default primitive list is empty. |
| To Email Address Primitives | Associate a send to email address and send to name with an optional group name and adds the information to a list of send to email addresses using a "to_email_address" primitive. The default primitive list is empty. |
| Courtesy Copy (CC) Email Address Primitives | Associate a cc email address and cc name with an optional group name and adds the information to a list of cc email addresses using a "cc_email_address" primitive. The default primitive list is empty. |
| Dropbox Email File Primitives | Creates and configures TReK email file dropboxes using "dropbox" primitives. An email file dropbox emails a file, placed in the dropbox, as a file attachment to a designated email address or email group. The file name of a file placed in an email file dropbox determines the subject of an email. The default primitive list is empty. |
| Dropbox Email Message Primitives | Creates and configures TReK email message dropboxes using "dropbox" primitives. An email message dropbox emails the content of a file, placed in the dropbox, to a designated email address or email group. The file name of a file placed in an email message dropbox determines the subject of an email. The default primitive list is empty. |
| Dropbox Texting Primitives | Creates and configures TReK texting dropboxes using "dropbox" primitives. A texting dropbox texts the content of a file, placed in the dropbox, to a designated cell phone number or texting group. The default primitive list is empty. |
Certificate Authorities:
If the inititialized TReK email library is configured to verify CA's (i.e., verify_cert_authorities true), the SetCertAuthoritesPathAndFilename library function allows a user to specify the location and file name of the CA. The cURL website provides CA certificates extracted from Mozilla in Privacy-Enhanced Mail (PEM) format. The website provides a new CA file once every few months. Download the CA PEM file (i.e., "cacert.pem") from http://curl.haxx.se/docs/caextract.html when configuring cURL to verify CAs.
Add Email Addresses:
The TReK email library provides two ways of adding "send to" address information to a list of email addresses and associating the email addresses with group names. The email library's configuration file includes "to_email_address" primitives that may be used to initialize the list of "send to" email addresses. Alternatively, the AddToEmailAddress function performs the same actions as the "to_email_address" primitive in the email configuration file but instead of describing the "send to" email address with a primitive string, the function's input parameters are the individual components of the primitive string.
The format of the "to_email_address" primitive string are as follows:
The first example associates a "to email address" with a group name. The second example associates no group name with a "to email address" (i.e., group_name ""). Note, if an email recipient's email address is associated with a group name, the recipient may be referenced using either their group name or email address. If an email address is never added to the list of email addresses using the email configuration file or the AddToEmailAddress function, a user may still send an email to the email address. However, the email message will not contain a "to email name" (i.e., to_email_name ""). The same email address may be added to multiple groups. The RemoveToEmailAddress function removes an email address from a group name.
Add Courtesy Copy Addresses:
The TReK email library provides two ways of adding "cc" address information to a list of email addresses and associating the email addresses with group names. The email library's configuration file includes "cc_email_address" primitives that may be used to initialize the list of "cc" email addresses. Alternatively, the AddCcEmailAddress function performs the same actions as the "cc_email_address" primitive in the email configuration file but instead of describing the "cc" email address with a primitive string, the function's input parameters are the individual components of the primitive string.
The format of the "cc_email_address" primitive string are as follows:
The first example associates a "cc email address" with a group name. The second example associates no group name with a "cc email address" (i.e., group_name ""). Note, if an email recipient's email address is associated with a group name, the recipient may be referenced using either their group name or email address. If a cc email address is never added to the list of cc email addresses using the email configuration file or the AddCcEmailAddress function, a user may still send an email to the email address. However, the email message will not contain a "to email name" (i.e., to_email_name ""). The same cc email address may be added to multiple groups. The RemoveCcEmailAddress function removes a cc email address from a group name.
Add Cell Phone Numbers:
The TReK email library provides two ways of adding cell phone information to a list of cell phone number and associating the cell phone numbers with group names. The email library's configuration file includes "text_cell_phone_number" primitives that may be used to initialize the list of cell phone numbers. Alternatively, the AddTextToCellPhoneNumber function performs the same actions as the "text_cell_phone_number" primitive in the email configuration file but instead of describing the cell phone number with a primitive string, the function's input parameters are the individual components of the primitive string.
The format of the "text_cell_phone_number" primitive string are as follows:
The first example associates a "text cell phone number" with a cell phone carrier and group name. The second example associates a "text cell phone number" with a cell phone carrier and no group name (i.e., group_name ""). Note, if a recipient's cell phone number is associated with a group name, the recipient may be referenced using either their group name or cell phone number. A cell phone number must be added to the list of "text to" cell phone numbers using the email configuration file or the AddTextToCellPhoneNumber function prior to sending a text message to the cell phone number. The same cell phone number may be added to multiple groups.The RemoveTextToCellPhoneNumber function removes a "text to" cell phone number from a group name.
Email Message Dropbox:
The TReK email library provides the ability to send the content of a text file, placed in an email message dropbox, as the message of an email to designated recipients. An email message dropbox may be created using the email library's configuration file or the CreateAnEmailMessageDropbox function. The email library's configuration file includes "dropbox email_message" primitives that may be used to create the dropbox during the initialization of the email library. Alternatively, the CreateAnEmailMessageDropbox function performs the same actions as the "dropbox email_message" primitive in the email configuration file but instead of describing the dropbox with a primitive string, the function's input parameters are the individual components of the primitive string.
Acceptable formats of the email message dropbox primitive string are as follows:
The email message dropbox primitive includes the dropbox path, the email address or group name that will receive the email and the successful transaction path. If the successful transaction path is defined, as shown in the first example, the dropbox will move the original file to the successful transaction directory if and only if the email was successfully delivered to the email server. If the successful transaction path is empty, as shown in the second example, the dropbox will delete the original file placed in the dropbox if and only if the email was successfully delivered to the email server. If the email message dropbox fails to send the email to the email server, the file will be renamed with a time tagged ".droperror" extension and remain in the dropbox. The email message dropbox will not attempt to email the content of a file with a ".droperror" extension in its filename. A group name must be added to the list of "send to" email addresses using the email configuration file or the AddToEmailAddress function prior to sending the content of a file using the email message dropbox.
Email File Dropbox:
The TReK email library provides the ability to send a file, placed in an email file dropbox, as an email file attachment to designated recipients. The email file dropbox supports many common file types including but not limited to text files, Portable Document Format (PDF) files, and Microsoft Office files. It does not support executable files. The email file dropbox will generate an error or fail to send file types that are not supported. An email file dropbox may be created using the email library's configuration file or the CreateAnEmailFileDropbox function. The email library's configuration file includes "dropbox email_file" primitives that may be used to create the dropbox during the initialization of the email library. Alternatively, the CreateAnEmailFileDropbox function performs the same actions as the "dropbox email_file" primitive in the email configuration file but instead of describing the dropbox with a primitive string, the function's input parameters are the individual components of the primitive string.
Acceptable formats of the email file dropbox primitive string are as follows:
The email file dropbox primitive includes the dropbox path, the email address or group name that will receive the email and the successful transaction path. If the successful transaction path is defined, as shown in the first example, the dropbox will move the original file to the successful transaction directory if and only if the email was successfully delivered to the email server. If the successful transaction path is empty, as shown in the second example, the dropbox will delete the original file placed in the dropbox if and only if the email was successfully delivered to the email server. If the email file dropbox fails to send the email to the email server, the file will be renamed with a time tagged ".droperror" extension and remain in the dropbox. The email file dropbox will not attempt to email a file as an attachment if a ".droperror" extension is part of the filename. A group name must be added to the list of "send to" email addresses using the email configuration file or the AddToEmailAddress function prior to sending a file as an email attachment using the email file dropbox.
Texting Dropbox:
The TReK email library provides the ability to send the content of a text file, placed in a texting dropbox, as a text to designated recipients. A texting dropbox may be created using the email library's configuration file or the CreateATextingDropbox function. The email library's configuration file includes "dropbox texting" primitives that may be used to create the dropbox during the initialization of the email library. Alternatively, the CreateATextingDropbox function performs the same actions as the "dropbox texting" primitive in the email configuration file but instead of describing the dropbox with a primitive string, the function's input parameters are the individual components of the primitive string.
Acceptable formats of the texting dropbox primitive string are as follows:
The texting dropbox primitive includes the dropbox path, the cell phone number or group name that will receive the text and the successful transaction path. If the successful transaction path is defined, as shown in the first example, the dropbox will move the original file to the successful transaction directory if and only if the text email was successfully delivered to the email server. If the successful transaction path is empty, as shown in the second example, the dropbox will delete the original file placed in the dropbox if and only if the text email was successfully delivered to the email server. If the texting dropbox fails to send the text email to the email server, the file will be renamed with a time tagged ".droperror" extension and remain in the dropbox. The texting dropbox will not attempt to text the content of a file with a ".droperror" extension in its filename. A group name must be added to the list of "text to" cell phone numbers using the email configuration file or the AddTextToCellPhoneNumber function prior to texting the content of a file using the texting dropbox.
Logging:
The TReK email library debug, progress, information, warning and error messages may be logged to a user specified file using the StartLoggingTReKMessages function. A user application may also write messages to the log file using the LogMessage function. The StopLoggingTReKMessages function stops writing messages to the log file and prepends a time tag to the log file name. The StartLoggingTReKMessages function and StopLoggingTReKMessages function are simple wrapper functions for the DS library's StartLoggingMessages function and StopLoggingMessages function.
Send Email:
The TReK email library's SendEmail function sends an email to an email address or group of email addresses and includes the email subject and email message. An application must call the InitializeToolkitEmail or InitToolkitEmail function prior to using the SendEmail function.
Send Email With a File Attachment:
The TReK email library's SendEmailWithFile function sends an email with a file attachment to an email address or group of email addresses and includes the email subject, email message and the path and file name of the file attached to the email. An application must call the InitializeToolkitEmail or InitToolkitEmail function prior to using the SendEmailWithFile function.
Send Text:
The TReK email library's SendText function sends a text to a cell phone number or group of cell phone numbers and includes the text. An application must call the InitializeToolkitEmail or InitToolkitEmail function prior to using the SendText function.
Save Email Configuration:
The TReK email library's SaveToolkitEmailConfig functions saves the current email configuration in a properly formatted email configuration file that can be used to initialize the email library using the InitToolkitEmail function. The email account password will not be saved in the configuration file. A user must add the password to the "email_account_password" tag in the configuration file if they want to store the password in the configuration file.
Final Notes
The TReK email library is thread safe. The maximum size of a text message varies for different cell phone carriers and ranges from 160 characters/bytes to over 900 characters/bytes. Your text message may also be broken up during transmission and then concatenated on the recipient’s phone. The maximum length of a TReK text message is 65,000 characters/bytes. The maximum length of an email with a file attachment is generally considered to be 10MB (email message size plus file attachment size). The maximum length of TReK email message without a file attachment is approximately 10 MB. Note, file attachments may become much larger than their original file sizes. This is due to the encoding employed by email servers when sending non text-based information. Successfully sending an email or text message to an email server does not gaurantee that the emil or text message will reach the designated recipient(s). A colon, ':', is not a valid TReK text character and will be changed to a period, '.', in all texts sent by the TReK email library. Gmail places sending limits on gmail accounts. In the unlikely event a user reaches one of the sending limits, the user will not be able to send a new messages for up to 24 hours. Please review Gmail's limits and policies for specific sending limits. Call the DSCleanUp function prior to exiting to gracefully shut down and properly clean up the TReK email library. Be sure to look at the examples provided with this library for a better understanding on how to use the library functions. Dynamic Link Libraries (DLLs) for all the examples may be found in a DLL folder in the TReK install directory.
Click on this link toolkit_email_device_api_ansi_c.h to go to the header file with all the functions.
Functions from other APIs
LogMessage
DSCleanUp
GetMessageCategoryAsPaddedString
TCAACGetHomeDirectory
TReK Email and Text API Configuration File Template:
toolkit_email_device_config.txt
Examples
The following examples are provided to show how to use the TReK Email and Text API functions:
Email Example
Example program initializes the email library using an imaginary email account and attempts to send an email to an imaginary group address using InitializeToolkitEmail, SetCertAuthoritesPathAndFilename, AddToEmailAddress, SendEmail, SaveToolkitEmailConfig and InitToolkitEmail functions.
Source File:
email_example/main.c
Email File Example
Example program initializes the email library using an imaginary email account and attempts to send an email with a file attachment to an imaginary email address using InitializeToolkitEmail, SetCertAuthoritesPathAndFilename, AddToEmailAddress, SendEmailWithFile, SaveToolkitEmailConfig and InitToolkitEmail functions.
Source File:
email_file_example/main.c
Texting Example
Example program initializes the email library using an imaginary email account and attempts to send a text to an imaginary group of cell phone numbers using InitializeToolkitEmail, AddTextToCellPhoneNumber, SendText, SaveToolkitEmailConfig and InitToolkitEmail functions.
Source File:
texting_example/main.c
Email Dropbox Example
Example program initializes the email library using an imaginary email account and attempts to send the content of a file, placed in a dropbox, as an email to the designated group address using InitializeToolkitEmail, SetCertAuthoritesPathAndFilename, AddToEmailAddress, CreateAnEmailMessageDropbox, SaveToolkitEmailConfig and InitToolkitEmail.
Source File:
email_dropbox_example/main.c
Email File Dropbox Example
Example program initializes the email library using an imaginary email account and attempts to send a file, placed in a dropbox, as an email with a file attachment to the designated group address using InitializeToolkitEmail, SetCertAuthoritesPathAndFilename, AddToEmailAddress, CreateAnEmailFileDropbox, SaveToolkitEmailConfig and InitToolkitEmail.
Source File:
email_file_dropbox_example/main.c
Texting Dropbox Example
Example program initializes the email library using an imaginary email account and attempts to send the content of a file placed in a dropbox as a text to the designated cell phone number using InitializeToolkitEmail, SetCertAuthoritesPathAndFilename, AddTextToCellPhoneNumber, CreateATextingDropbox, SaveToolkitEmailConfig and InitToolkitEmail.
Source File:
texting_dropbox_example/main.c
Additional Dependencies
The TReK Email and Text API is also dependent on the following libraries.
trek_toolkit_common_api
trek_toolkit_ds_api
trek_toolkit_dropbox_device_api
trek_dropbox_device_api
libcurl
libcrypto
libssl