Sent API Documentation


This document can also be found online at sentapi.com/documentation


Introduction

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.

Upgrading

Below you'll find information on how to upgrade.

v1.1 to v1.2
  • You will need to make a small adjustment to your Sent database. Use the file "v1.1-v1.2.sql" in the /db_upgrade folder and execute the SQL statements within your Sent database (this will add two columns to your config table)
  • Update the following folders:
    – /application (every subfolder except for the /application/config folder)
v1.2 to v1.3
  • Update the following folders:
    – /application (every subfolder except for the /application/config folder)

Before Installing

Requirements

To be able to install Sent API, you must have the following:

  • Apache2 server
  • PHP 5.1.6+
  • MySQL (mysqli support)
  • (Windows/IIS is experimental)
  • Server capable of sending mail (i.e. sendmail) OR
  • Access to a STMP server (ie gmail or your own server)

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.

Structure

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.

CodeIgniter

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 :)


Installation

Step 1: Upload Files

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.

Step 2: Installation Script

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.

Step 3: Configuration

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:

Private API
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.

Confirmation message
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.

Default subject
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.

Confirmation email
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.

Usage

Basic Usage

The API works as follows:

  1. You create a form and point it to your API url.
  2. If this is the first time a form is submitted for the specified email address (or email ID), an verification email is sent to the email address. This email contains a link which the owner has to click to verify the email address. After loading the URL, the user will see a confirmation message saying the email address is now ready to receive form data.
  3. From now on, every form submitted for the specified email address (or email ID) will result in an email containing the form data being emailed to the specified email address.

method="POST"
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 regular email address:
<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>
Basic usage with email ID:
<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>


Advanced Usage

To get more advanced usage from the Sent API, you can use several special form fields:

  • Custom subject
    Sets a custom subject for the email sent by the API
    <input type="hidden" name="_subject" value="My awesome subject">
  • Custom reply to
    Sets a custom reply to value for the email sent by the API
    <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">
  • Redirection
    Allows you to specify a URL to redirect the user to after successfully submitting the form and sending out the email
    <input type="hidden" name="_after" value="http://google.com">
  • Honey pot
    The honey pot field adds an additional spam protection to your forms. By inserting this hidden field, you're allowing the API to detect automated submissions. If the API fields a value inserted into the honey pot field, this is a strong indication that the submission as automated and it will be marked as spam. Please note that the "value" attribute of this field must remain empty.
    <input type="text" name="_honey" value="" style="display:none">
  • Custom confirmation message for the user
    This form allows you specify a custom confirmation message which is shown to the user after submitting the form. Setting this field overrides the default confirmation message.
    <input type="hidden" name="_confirmation" value="<b>Thank you!</b> We have received your message and will get back to you asap.">
  • CC and BCC recipients Use the following syntax to specify one or more CC and/or BCC recipients. Please note the name of this field is "cc[]" or "bcc[]". This allows you to specify any number of entries, rather then just one.
    <input type="hidden" name="cc[]" value="[email protected]">
    <input type="hidden" name="bcc[]" value="[email protected]">


Validating form data

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.

Validation syntax
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:

Rule Description Example
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[6]
max_length Returns FALSE if the form element is longer then the parameter value. max_length[12]
exact_length Returns FALSE if the form element is not exactly the parameter value. exact_length[8]
greater_than Returns FALSE if the form element is less than the parameter value or not numeric. greater_than[8]
less_than Returns FALSE if the form element is greater than the parameter value or not numeric. less_than[8]
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.



Submitting forms with files

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



API Admin

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:

  • Form submissions
  • Email IDs
  • Attachments

In addition to the items mentioned above, you can also configure the behaviour of the API using the settings page.



Submissions

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.



Email IDs

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:

  • Email address
    This is the email address to which form data will be send
  • Email mask
    This is the email ID/mask which can be used as an alternative to using the regular email address, allowing the regular email address to be hidden for bots and crawlers looking for email addresses in web sites.
  • Verification code
    This is the verification code used in the verification email send to new email addresses to verify that email address.
  • Verified?
    Reads either "yes" or "no", depending on wether or not the owner of the email address has clicked the verification link emailed to him or her.
  • Active?
    If set to "on", the email address is allowed to receive form submissions, if "off" the email address will not receive emails. If the Private API setting is turned on, all new email addresses will need to be activated by the API administrator. If turned off, all new email addresses will automatically be activated.


Attachments

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.