Skip to main content

Receiving Inbound Emails


Our inbound email works by catching all emails addressed to a subdomain of your domain. For example if your domain is, and you choose the subdomain inbound any emails sent to * will be handled. We POST all emails onto a webhook address of your choice, defined on the inbound_emails page in our application.

We will attempt to send to your endpoint five times with an increasing gap in between each send, after which we will declare the email as failed and will not try again.


Your domain must have passed DKIM verification and your organization must have an active plan to accept inbound emails


To setup Inbound Emails you need to add a CNAME DNS record that points from your chosen inbound subdomain on your domain to This will ensure that any emails sent to <inbound-subdomain>.<your-domain> are sent to our servers. The specific instructions and example records are available on the Inbound Emails page of your Domain.

After you have setup your DNS records, you just need to add an Endpoint URL, which can be any https address. For testing, you can use a tunnel to your local machine like ngrok or a service like


There are four statuses that an inbound email can be in after it has been received by our servers:

  • Queued: Email received and has been added to the queue for sending to the endpoint
  • Success: The POST request to the endpoint succeeded, with an HTTP status code between 200 and 300
  • Retrying - The POST request to the endpoint failed. We attempt to send 5 times, at vary intervals, after which the email will move to the Failed state
  • Failed - The POST request has permanently failed, either through exhausting the number of retries or another permanent failure (e.g. HTTP connection errors or timeouts that are unlikely to succeed in the near future)

Email Payload Reference

Emails are sent as HTTP POST requests with a JSON body containing the following parameters:

fromRequiredstringPerson A <>
headersRequiredArray of strings["Received: from localhost...", "DKIM-Signature: v=1 a=rsa...;]
rawRequiredstringThe full raw email as described in RFC 822
toOptionalstringPerson B <>
subjectOptionalstringEmail Subject
ccOptionalstringPerson C <>
bccOptionalstringPerson D <>
htmlOptionalstring<h1>Email Contents Here</h1>
textOptionalstringText Email Contents
attachmentsOptionalArray of AttachmentsSee Attachments

Properties that are marked as Optional may not appear as a parameter in the body


Attachments are sent as an array, in the following structure:

contentContent of the attachment, encoded as a base64 stringRequiredstringPerson A <>
typeType of the attachment, usually just "attachment"Requiredstringattachment
contentTypeMIME type of the messageRequiredstringtext/plain
contentDispositionContent disposition type for the attachmentRequiredstringattachment
filenameFile name of the attachment, if providedOptionalstringimage.png
headersHeaders for the attachmentRequiredArray of strings[Header: content, ...]
checksumAn MD5 hash of the attachment contentRequiredstringabc
sizeMessage size in bytesRequirednumber123
contentIdThe header value from Content-IDOptionalstring<abc>
cidcontentId without < and >Optionalstringabc
relatedAttachment should not be offered for download as a "standard" AttachmentOptionalbooleantrue