Skip to main content

Receiving Inbound Emails

Overview

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

All plans come with unlimited domains, so if the inbound subdomain is unavailable on your domain, you can always create another subdomain and use that (e.g. emails.inbound.test.com).

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.

caution

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

Setup

To setup Inbound Emails you need to add a CNAME DNS record that points from inbound on your domain to inbound.mailpace.com. This will ensure that any emails sent to inbound.<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 https://httpstat.us/.

Statuses

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:

NameOptionalityTypeExamples
fromRequiredstringPerson A <person_a@test.com>
headersRequiredArray of strings["Received: from localhost...", "DKIM-Signature: v=1 a=rsa...;]
messageIdRequiredstring<3baf4caf-948a-41e6-bc5c-2e99058e6461@mailer.mailpace.com>
rawRequiredstringThe full raw email as described in RFC 822
toOptionalstringPerson B <person_b@test.com>
subjectOptionalstringEmail Subject
ccOptionalstringPerson C <person_C@test.com>
bccOptionalstringPerson D <person_d@test.com>
inReplyToOptionalstring<3baf4caf-948a-41e6-bc5c-2e99058e6461@mailer.mailpace.com>
replyToOptionalstringbounces+abcd@test.com
htmlOptionalstring<h1>Email Contents Here</h1>
textOptionalstringText Email Contents

| attachments | Optional | Array of Attachments | See Attachments |

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

Attachments

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

NameDetailsOptionalityTypeExamples
contentContent of the attachment, encoded as a base64 stringRequiredstringPerson A <person_a@test.com>
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