Parse inbound email
What is inbound parsing?
Receiving email is a much harder task than sending email for developers since there’s no easy way to retrieve the actual message from naturally-unstructured incoming emails. “A real pain” or “a headache” is what developers usually answer when asked about processing incoming emails.
This leads to poor user experiences when emails that are meant to be replied (e.g. messages from buyers on a marketplace) come from a no-reply address and feature a “Reply” button that takes the user to a cumbersome reply flow on an app or website.
Inbound parsing at Brevo
The parsing technology at Brevo comes from the acquisition of the MailClark startup, whose technology has converted millions and millions of unstructured emails into formatted chat messages since 2015. Using state-of-the-art algorithms and machine learning techniques, the actual message and signatures are retrieved from raw emails and converted into Markdown.
Emails are received and processed on our end, and are then sent to you as a structured JSON payload (described in the next chapter) via a webhook.
Setting up your Inbound parsing webhook
Preparing your domain
For the set-up, you will need to determine two things first:
- The receiving domain (or subdomain) for the emails to be parsed. It must be a different domain than the one used for sending email. We recommend creating a subdomain such as
reply.yourdomain.com. - The webhook URL that Brevo will call to send the events when an inbound email has been parsed.
Make sure that your domain is verified with Brevo.
Then, you will need to delegate the receiving domain to Brevo: This is done by updating your DNS configuration for reply.yourdomain.com so that emails sent to this domain are received on Brevo servers. There are 2 records that you need to add:
DNS changes can take several hours to spread over the internet, so it’s important to do this configuration as soon as possible.
Creating the webhook
The same endpoints used to create, get, update and delete webhooks for Marketing and Transactional events are available to manage Inbound parsing webhooks.
As you can see in the sample POST request below, the differences compared to events-related webhooks are:
- Use
inboundfortypeandinboundEmailProcessedforevents - Specify your receiving
domain
With the above configuration, any email sent to *@reply.yourdomain.com will be received by our API, parsed and converted to JSON, and the result POST-ed to http://example.domain.com/1brxxxxxx5p1.
Parsed email payload
The JSON body will contain a top-level items array, listing the emails that were received. Each email will have the following properties:
The Mailbox object
The Attachment object
Use the DownloadToken(see below) to retrieve attachments using this endpoint.
Sample payload
Logs and inbound email parsing activity
Two endpoints are available for you to access logs and monitor inbound parsing activity:
-
List and filter by date and/or sender the emails received via your Inbound parsing webhook.
-
Get the full details for one particular email received via your Inbound parsing webhook.
Ongoing improvement
Given the diversity of email apps, human languages and formatting possibilities, it is impossible to guarantee a 100% success rate on inbound parsing. Nevertheless, we constantly keep on bettering the performance of our parsing engine—you can participate in this ongoing improvement by reporting parsing failures.
It is important to note that depending on the reason behind the parsing failure, we might or might not be able to correct a given error. If, for instance, quoted replies weren’t stripped because an email app uses an unusual formatting, we can integrate this unknown formatting to our algorithm and this will correct your problem once the parsing engine is updated. On the other hand, if a segment was wrongly identified as a signature, we won’t necessarily be able to correct your particular error since signature detection uses machine learning. But your failure reports do help our data scientists fine tune what they “teach” the machine.
Please send your failure report to contact at brevo.com with the following details:
- Subject line: Inbound Parsing API Failure
- JSON payload (or relevant excerpt of the payload + UUID)
- Reason of failure:
- Quoted replies not removed from
ExtractedMarkdownMessage - Signature not removed
ExtractedMarkdownMessage - Truncated
ExtractedMarkdownMessage - Truncated or empty
ExtractedMarkdownSignature - Message content wrongly detected as
ExtractedMarkdownSignature
- Quoted replies not removed from
