How do I use forms with 3mail?

The 3mail module accepts form submissions, allowing you to build a custom form for your web page and submit the data collected from that form to 3mail.

Submitting form data

The form submission URL is /api/email/_submit and it accepts POSTs.

The domain for the submit URL varies based upon where your LibraryH3lp account is located.

Form data must include:

• from: the guest's email address
• mailbox: your 3mail mailbox's name, which is the same as the queue name
• subject: a subject line to be used for the email sent to 3mail

Form data may include:

• tag[]: By default emails are sent to your Inbox. Use tag[] to send the email to a different tag or tags.

Any other custom form data is included in the body of the message sent to 3mail.

Simple example form

For a mailbox named my-queue-name with a custom form data value of question.

Emails sent by using the form below will arrive with two tags -- Inbox and WebForm. WebForm is just an example tag, you would of course change this to match one of your tags.  You can add as many tags as you'd like by adding more tag[] inputs to your form.

If you are not using JavaScript to submit your form:

• Add a method attribute to your form element and set it to post.
• Add an action attribute to your form element and set it to the form submission URL described above.

Example jQuery to submit a form

$('#offline-contact-form').submit(function(event) {
  event.preventDefault();
  $.ajax({
    type: 'POST',
    url: 'https://libraryh3lp.com/api/email/_submit',
    data: $(this).serialize(),
    error: function() {
      $('#offline-contact-form').html('Uh oh! There was an error.');
    },
    success: function() {
      $('#offline-contact-form').html('Form submited successfully!');
    }
  });
});

Example (plain) JavaScript to submit a form

Also you'll need to slightly modify the form HTML to remove the type attribute from and add an onclick attribute to the submit button which calls the submitForm function.

Like this: <button type="button" onclick="submitForm()">Submit</button>

function submitForm() { 
  // Gather form fields
  var formFields = document.querySelectorAll('#offline-contact-form [name]');
  formFields = Array.prototype.slice.call(formFields);
  var formParams = formFields.map(function(el) {
    return encodeURIComponent(el.name) + '=' + encodeURIComponent(el.value);
  }).join('&');
  
  // POST form fields
  var url = 'https://libraryh3lp.com/api/email/_submit';
  var xhr = new XMLHttpRequest();
  xhr.open('POST', url);
  xhr.setRequestHeader('Content-type', 'application/x-www-form-urlencoded');
  xhr.onload = function() {
    var form = document.getElementById('offline-contact-form');
    form.innerHTML = 'Form submitted successfully!';
  }.bind(xhr);
  xhr.send(formParams);
  return false;
}

Tip to Avoid Bot Spam

Consider adding a honey pot to your form.  A honey pot is a hidden bogus form input that a real person wouldn't see and thus wouldn't fill out.  Using JavaScript, you can check the honey pot for a value before submitting the form.  If there's a value set for the honey pot, this is most likely a bot so don't submit the form. 

For best accessibility with your honey pot, place the hidden field after the form submit button and give it a label indicating that screen reader users should leave it empty.

Example jQuery from above updated to use a simple honey pot to avoid bot spam

Note: This code assumes you have a hidden input in your form named email.

$('#offline-contact-form').submit(function(event) {
  event.preventDefault();
  var isSpamBot = $(this).find('input[name=email]').val();
  if (!isSpamBot) { 
    // Remove the honey pot from the form.
    $(this).children('input[name=email]').remove(); 
  $.ajax({
    type: 'POST',
    url: 'https://libraryh3lp.com/api/email/_submit',
    data: $(this).serialize(),
    error: function() {
      $('#offline-contact-form').html('Uh oh! There was an error.');
    },
    success: function() {
      $('#offline-contact-form').html('Form submitted successfully');
    }
  });
});

FAQ URL: