Mailthis.to Documentation



Introduction

Mailthis.to is an API which allows you to process form submissions from anywhere on the Internet and send out emails containing the form data.

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="[email protected]" method="post">

Email address or email ID
The Mailthis.to 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="[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="//mailthis.to/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 Mailthis.to, 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

Mailthis.to 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="[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

Mailthis.to 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="[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>