Parse inbound email
What is inbound parsing?
Receiving email is harder for developers than sending it, because there’s no easy way to retrieve the actual message from unstructured incoming emails. Developers commonly describe processing incoming emails as “a real pain” or “a headache”.
This leads to poor user experiences when emails meant to be replied to (for example, messages from buyers on a marketplace) come from a no-reply address and feature a “Reply” button that pushes the user into a cumbersome reply flow on an app or website.
Inbound parsing at Brevo
Brevo’s parsing technology comes from the acquisition of MailClark, whose technology has converted millions of unstructured emails into formatted chat messages since 2015. Using algorithms and machine learning, the actual message and signatures are extracted from raw emails and converted into Markdown.
Emails are received and processed on our end, then delivered 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 setup, determine two things first:
- The receiving domain (or subdomain) for the emails to be parsed. It must differ from the domain used for sending email. We recommend creating a subdomain such as
reply.yourdomain.com. - The webhook URL that Brevo will call to send events when an inbound email has been parsed.
Make sure your domain is verified with Brevo.
Next, delegate the receiving domain to Brevo. Update your DNS configuration for reply.yourdomain.com so emails sent to this domain are received on Brevo servers. Add the following two records:
DNS changes can take several hours to propagate, so apply this configuration as early as possible.
Creating the webhook
The same endpoints used to create, get, update and delete webhooks for Marketing and Transactional events also manage Inbound parsing webhooks.
The differences compared to events-related webhooks, shown in the sample POST request below, are:
- Use
inboundfortypeandinboundEmailProcessedforevents - Specify your receiving
domain
With this configuration, any email sent to *@reply.yourdomain.com is received by our API, parsed, converted to JSON, and POSTed to http://example.domain.com/1brxxxxxx5p1.
Parsed email payload
The JSON body contains a top-level items array listing the received emails. Each email has 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 let you access logs and monitor inbound parsing activity:
-
List and filter received emails by date and/or sender via your Inbound parsing webhook.
-
Get full details for a particular email received via your Inbound parsing webhook.
Ongoing improvement
Given the diversity of email apps, languages, and formatting, a 100% success rate on inbound parsing is impossible. We continuously improve the parsing engine, and you can contribute by reporting parsing failures.
Depending on the cause of the parsing failure, we may or may not be able to correct a given error. For example, if quoted replies aren’t stripped because an email app uses an unusual format, we can integrate that format into our algorithm and fix the issue once the parsing engine is updated. On the other hand, if a segment is wrongly identified as a signature, we may not be able to correct that specific case because signature detection uses machine learning. Your failure reports still help our data scientists fine-tune what they “teach” the model.
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 for 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
