Is it free?

Yep! Emailhooks is meant to be an easy fix to get projects up and running. If you need to handle lots of mail, have big attachments, or need more control, you should set up your own receiver (it's really easy).

Emailhooks is a best-effort service and I can't garuantee uptime or that everything will be perfect here. That said, emailhooks will be up as long as google app engine is up and I won't shut the service down without letting you know first.

What does the request look like?

Requests are sent as POSTs with Content-Type: application/json:

  "sender": "tom@example.com",
  "to": [
  "cc": [
  "date": "Fri, 10 Mar 1876 15:54:49 -0500",
  "subject": "Urgent!",
  "html_body": "<html><div dir=\"ltr\">Mr. Watson, come here — I want to see you.</div></html>",
  "plain_body": "Mr. Watson, come here — I want to see you.",
  "attachments": [
      "filename": "example.txt",
      "payload": "baWEfsdv25DF654... base64"
  • to/cc fields are always arrays, even if there are 1 or no addresses
  • plain_body is just the plain text version of html_body
  • attachment payloads are base64 encoded

Validating requests?

To validate that a POST is coming from emailhooks, an HMAC-SHA1 signature is generated for each request and is included in the headers as X-Hook-Signature. The signature is created using the body of the request and a key unique to each user. You can find the key on your hook list page ( XXXXXXXXXX).

At your endpoint you can compute the signature using your secret key and compare it to the one in the request header to know if the request is valid. In python, for example, you could do this like:
signature = hmac.new(bytes(key), bytes(request.body), hashlib.sha1).hexdigest()


Attachments are ok as long as the whole email is under 500kb (including the attachments). Emails larger that 500kb will be ignored. This limit is in place to prevent the service from being swamped with big attachments. 500kb isn't much but it will probably work for small documents like csv files, small excel docs, etc.

If you need work with larger attachments you can set up your own receiver on google app engine pretty easily with this project. This will let you handle files up to 30mb.

Any limitations?

  • 10 hooks per user
  • Emails must be < 500kb (see above 🡑)

Can I use my own domain?

If your registrar offers email forwarding you probably can. Just set an address on your domain to forward to your emailhooks recipient. You could also forward all emails from a catch-all address to your emailhooks recipient and use logic on your endpoint based on the email's to field.

Some registrars require you to verify the forward email first by sending an email to that address. You will need to have your hook destination ready to listen to that verification.

What data does emailhooks store?

Emailhooks keeps a log of each outgoing post request: response, response code, size, number of attachments. Actual incoming mail isn't stored.


Open an issue.