This document can also be found online at sentapi.com/documentation
Sent API is a self-hosted API which allows you to process form submissions from anywhere on the Internet and send out emails containing the form data.
Sent API is a "install-once", "use-unlimited" solution, meaning you install it once after which you can use it with unlimited web sites and forms.
For more general information about the API, please have a look at the public web site: http://sentapi.com.
Below you'll find information on how to upgrade.v1.1 to v1.2
To be able to install Sent API, you must have the following:
The above requirements basically means it will run perfectly fine on all LAMP hosting environments. As far as Windows/IIS goes, we have seen the API work great on this platform, but since we haven't been able to test this setup extensively, we can't guarantee it will work smoothly.
Like mentioned before, Sent API is built using CodeIgniter and Flat UI Pro. To learn more about CodeIgniter, please visit the CodeIgniter website or read the online documentation here. To learn more about Flat UI Pro, please have a look here.
Before continuing with the installation of Sent API, please make sure your hosting is capable of hosting CodeIgniter 2.1.4. In 99% of the cases, this won't be a be a problem :)
You'll need to start with uploading the Sent API files. You can either upload "Sent.zip" and unpack it on your hosting or unpack "Sent.zip" locally first and then upload the files. Unpacking the file "Sent.zip" will create a folder named "Sent" which contains all the application files.
The Sent API can run either in the root folder of your hosting, or in a sub folder.
After successfully uploading the files, open your browser and navigate your browser to the URL where you have just uploaded your files. When loading the software for the first time, it will automatically present you with an installation page.
On this installation page, you will need to enter your database connection details, plus the user name (email address) and password you'd like to use to access the Sent API admin panel once installation is completed.
Please note that the web server will need to be able to write to the database configuration file located in application/config/database.php. In most cases, this will work as is. If the installation script detects a problem, it will show an error message when first loading the installation script.
After completing the form and submitting the details, the API will be installed and you will receive a confirmation message together with a button which links to the setup/login page.
Removing the "index.php" from the URLs
To make the URLs look a bit nicer, you can opt to remove "index.php" from the URLs. To achieve this, you'll need to rename "/_htaccess" to ".htaccess" and edit the configuration file found at application/config/config.php, and set the variable "$config['index_page']" to an empty string ("") by removing "index.php". Please note that this requires your Apache2 server to have mod_rewrite enabled.
After completing the installation of the Sent API on your host, it's now time to configure it to work properly. Most of the configuration can be accessed through the admin panel. After logging in, click the "Administator" dropdown item from the menu and click "Settings" to access the configuration panel.
We'll now briefly explain all the available settings:
If set to "on", this means you're API is in private mode and newly registered email addresses (wanting to receive form data) will have to be manually activated by the administrator. When set to "off", newly registered email addresses are active after registering and don't require manual activation by the administrator. Please note that this feature is separate from the "email verification process" (which makes sure the owner of an email address has actually opted to use the API) which always has to the completed for a new email address.
Administrator email address
The email address of the API administrator. This is used in certain error messages only, and is separate from the admin email address used to log into the admin panel.
This is the confirmation message shown to users after they successfully submit a form. This message can be overwritten by specifying a custom confirmation using a hidden "_confirmation" field inside the form. If a redirection is specified, then obviously this message won't be shown
Emails sent from
The email address shown as the sender of emails containing the submitted form data. If you're using SMTP (more about this further down), you're best off making sure this email address matches the one used with your SMTP server in order to prevent your emails being caught in spam filters
Emails from name
A name to go with the email sending address.
Sets the default subject of emails sent by the API containing submitted form data. This can be overwritten by specifying a custom subject inside the submitted form.
This is the default confirmation email sent to users submitting the form. If empty, no confirmation email will be send. You can use other form data to populate the confirmation message, by including the form name enclosed by "%" characters. For example, you want to include the contents of a field named "email", you would use "%email%".
Confirmation email subject
This is the subject of the default confirmation email sent to users submitting the form.
Store attachments on server
If set to "on", files send with submitted forms will be stored on your server as well as being send as an attachment. If you'd like to use this features, you will have to make sure you have specified a writable folder in the application/config/upload.php configuration file. This is set to "uploads" by default.
Other then the path, the upload.php configuration file contains other settings regarding the uploading and storing of files.
SPAM words and phrases
This allows you to set words and or phrases will be used by the API to check incoming data. If one or more of these words or phrases are found inside submitted form data, the submission will be considered as SPAM and no emails will be send. Make sure you enter one word or phrase per line.
The API works as follows:
For the API to function properly, it's important you submit your form data as POST data, rather then GET data. To achieve this, add the following attribute to your opening form tag method="POST". A proper opening form tag would look something like this:
<form action="//yourdomain/sent/api/[email protected]" method="post">
Email address or email ID
The Sent API allows you to submit directly to an email address, or instead of using your email address, use an email ID instead. This email ID is simply a unique string which the API recognises as being linked to your email address. By using an email ID instead of a regular email address, you prevent your email address being embedded in the form markup and therefor out of hands of bots crawling the web to harvest email addresses.
Creating an email ID is very simple. Once the API is installed, navigate to your Setup/Login page and enter your email address. Click the blue button and the software will display your email ID, together with the entire API url to setup with your form. This email ID remains the same, so whenever you've lost it, simply enter it again on the Setup/Login page and the software will show it again.
Basic usage with email ID:
<form action="//yourdomain/sent/api/[email protected]" method="post"> <input type="text" name="name"> <input type="email" name="email"> <textarea name="message"></textarea> <input type="submit" value="Send"> </form>
<form action="//yourdomain/sent/api/danmu6QvZH9qgNWuGFNh" method="post"> <input type="text" name="name"> <input type="email" name="email"> <textarea name="message"></textarea> <input type="submit" value="Send"> </form>
To get more advanced usage from the Sent API, you can use several special form fields:
<input type="hidden" name="_subject" value="My awesome subject">
<input type="hidden" name="_replyto" value="[email protected]">
Instead of specifying a static custom "reply to" address, you can also choose to use an email address entered by the user of the form. In order to do this, give your custom "replyto_" field a value of "%" followed by the name of the field. Let's assume you have a field named "email" which value you'd like to use for your custom "reply to" field, then you'd give you "reply to" field a value of "%email".
<input type="hidden" name="_replyto" value="%email">
<input type="hidden" name="_after" value="http://google.com">
<input type="text" name="_honey" value="" style="display:none">
<input type="hidden" name="_confirmation" value="<b>Thank you!</b> We have received your message and will get back to you asap.">
<input type="hidden" name="cc" value="[email protected]"> <input type="hidden" name="bcc" value="[email protected]">
Sent API comes with built-in form validating capabilities. You can specify a variety of rules for your data; and if the submission does not pass the validation process, the user will be shown a message detailing which validation rules were not passed.
The validation syntax is simply and straightforward. You simply add a hidden field for each form field you'd like validated, and you name this hidden field "_valid[field_name]" where you replace "field_name" with the name of the field. Please see the basic example below:
<form action="//yourdomain/sent/api/[email protected]" method="post"> <input type="hidden" name="_valid[name]" value="required"> <input type="hidden" name="_valid[email]" value="required|valid_email"> <input type="hidden" name="_valid[message]" value="required"> <input type="text" name="name"> <input type="email" name="email"> <textarea name="message"></textarea> <input type="submit" value="Send"> </form>
In the example above, the form contains three fields to be filled out by the user: name, email and message. Accordingly, three hidden validation fields have been added to the form as well. The "name" field must validate as required, meaning it can not be left empty. The same applies to the "message" field. The "email" field is also required, and in addition it must validate as a proper email address. If any of these requirements are not met, the user will get an error message explaining what is wrong with their data.
Below you'll see an overview of all available validation rules:
|required||Returns FALSE if the form element is empty.|
|min_length||Returns FALSE if the form element is shorter then the parameter value.||min_length|
|max_length||Returns FALSE if the form element is longer then the parameter value.||max_length|
|exact_length||Returns FALSE if the form element is not exactly the parameter value.||exact_length|
|greater_than||Returns FALSE if the form element is less than the parameter value or not numeric.||greater_than|
|less_than||Returns FALSE if the form element is greater than the parameter value or not numeric.||less_than|
|alpha||Returns FALSE if the form element contains anything other than alphabetical characters.|
|alpha_numeric||Returns FALSE if the form element contains anything other than alpha-numeric characters.|
|alpha_dash||Returns FALSE if the form element contains anything other than alpha-numeric characters, underscores or dashes.|
|numeric||Returns FALSE if the form element contains anything other than numeric characters.|
|integer||Returns FALSE if the form element contains anything other than an integer.|
|is_natural||Returns FALSE if the form element contains anything other than a natural number: 0, 1, 2, 3, etc.|
|is_natural_no_zero||Returns FALSE if the form element contains anything other than a natural number, but not zero: 1, 2, 3, etc.|
|valid_email||Returns FALSE if the form element does not contain a valid email address.|
|valid_emails||Returns FALSE if any value provided in a comma separated list is not a valid email.|
|valid_ip||Returns FALSE if the supplied IP is not valid. Accepts an optional parameter of "IPv4" or "IPv6" to specify an IP format.|
Sent API is capable of handling forms with file uploads with a breeze. Simply include a file input element in your form, make sure it's "name" attribute is set to file and you're all set!
Below you'll see an example of a form with a file input element:
<form enctype="multipart/form-data" action="//yourdomain/sent/api/[email protected]" method="post"> <input type="text" name="name"> <input type="email" name="email"> <textarea name="message"></textarea> <input type="file" name="file"> <input type="submit" value="Send"> </form>
Using the application/config/upload.php file, you can configure how file uploads should be handled. You can define file types, file size, dimensions (when dealing with images) etc. Please refer to the upload.php file for an overview of the available settings.
Using the settings page inside the admin area, you can configure the API to store the file permanently on your server as well as sending them by email
Sent API comes with a handy admin panel which allows to you to manage the data flowing through the API. Within this admin panel, you can keep track and manage the following:
In addition to the items mentioned above, you can also configure the behaviour of the API using the settings page.
This panel will show you all form submissions, including the ones which have been marked as spam. You can use the handy filters in the top right corner to filter out spam, un-verified or disabled submissions.
You can also use the search bar to find specific submissions (search includes the submitted data).
Both the "user agent" and the "data" columns can contain additional data which is hidden by default. Clicking any of these fields will expand the field and show additional data.
This panel allows you to track all current users of the API (meaning email addresses which are setup to receive form submissions).
The email IDs tables contains the following columns:
This panel allows you to manage the files uploaded with form submissions. Please note that if your API is configured not to store files on the server, this page will not show any files.
It's also important to set the file path in application/config/upload.php correctly, as it's used by this page to read the files on your server.