Skip to content
Yetto Docs

Creating a contact form

For Yetto users who want to give their customers a contact form to fill out and submit, we offer an API endpoint to send form data. You'll need to send a couple of fields, hash the data with a secret that we give you, and include the hash in a header. Here we'll walk you through the process.

Creating a form

To start, you'll need to create a form in your application or on your site to send us data in a POST request. You'll need to collect the following data to send to us:

  • The customer's email address. We use this when creating the conversation in Yetto so that your responses go to the customer's inbox.
  • A subject line. This will be the title of the conversation in Yetto. You can create this yourself or ask the customer to create one.
  • A text body. This is the body of the message that you'll see in Yetto. We support full markdown, so feel free to send with all the markdown formatting you or your customers want.

Formatting the required fields

The three required fields should be included in the body of your POST request.

fielddata typerequired
from_emailstringtrue
subjectstringtrue
text_bodystringtrue

The body must be in JSON format to be accepted by Yetto.

Hashing your data

In your email plug settings, there will be a "Contact form secret" that you'll use to hash your request.

A screenshot of the email plug settings for the contact form secret and contact form URL. A screenshot of the email plug settings for the contact form secret and contact form URL.

Yetto uses an HMAC hex digest to compute the hash, with that string as the key. In order to get the correct hash you'll need to:

  1. Hash the body of your request using a SHA256 HMAC hex digest using your unique form secret.
  2. Prepend the string sha256= to the beginning of the calculated hash.

For example, if your secret and request body look like this:

  • secret: this-is-a-secret
  • body:
{
    "from_email": "j.doe@example.com",
    "subject": "Help!",
    "text_body": "I need help."
}

then your calculated and formatted hash should be sha256=43b170c108c13d652f2427ded79b8920a766c07dede299622de8232a9d113304.

There are libraries and implementations for calculating these hashes, so you should be able to find one for whatever framework or language you're working with.

If you are working in Ruby, your code might look something like this:

signature = 'sha256=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), contact_form_secret, request_body)

Every framework and language is a little different, so we'll let you decide the best way to handle this in your form.

Sending your data

In your email plug settings, there will be a "Contact form endpoint" unique to your plug installation and inbox. Send your data there by:

  1. Putting your calculated hash in a X-Yetto-Form-Signature header.
  2. Including your data in JSON format as the request body.
  3. Sending the POST request to the unique contact form endpoint URL.

On success, you will receive a 201 response from Yetto and the message should appear in your inbox as an email message from your customer. Good job!

Sample server

Here's a minimal example using Ruby which demonstrates the requirements for sending your data:

require "openssl"
require "json"
require "net/http"
require "uri"

message = {
  "from_email": "monte.m@yetto.app",
  "subject": "TEST: How are ya?",
  "text_body": "I love your app.",
  # optional! if omitted, `from_email` is used
  "author": {
    "name": "Monte Melkonian"
  }
}

# this is a dummy value; find the real one on your settings page
secret = "000000beb61fd8156223d16a31a3638a43802200"

signature = "sha256=" +
  OpenSSL::HMAC.hexdigest(
    OpenSSL::Digest.new("sha256"),
    secret,
    message.to_json
  )


# this is a dummy value; find the real one on your settings page
url = "https://email.plugs.yetto.app/email/2023-03-06/form/pli_000000000000076WFRX10QVVPS"

Net::HTTP.post(URI(url),  message.to_json, { "X-Yetto-Form-Signature" => signature, "Content-Type" => "application/json"})