Overview
Each company has a personal@outbox.email.e-invoice.be address. When you send an email with an invoice or credit note attachment (UBL XML or PDF) to this address, e-invoice.be makes a draft document from the attachment. The Mailbox is the record of these emails: it shows which emails arrived, which document each email made, and why an email failed.
Use the Mailbox when:
- Your ERP or accounting tool can email invoices but cannot call an API.
- You want to add the address in BCC to the emails that you already send to your customers.
- You want to start with e-invoicing before you build an API integration.
The Mailbox is for documents that you send (outbound). To read documents that you receive through Peppol, see Receive documents.
Find the mailbox address
The address is unique for each company. You can get it in two ways:- In the app: open the company settings in app.e-invoice.be. The card E-Invoice Email Conversion shows the BCC Email Address with a copy button.
- With the API: call
GET /api/me/and read the fieldbcc_recipient_email.
cURL
Response (extract)
bcc_recipient_email is null, the Mailbox is not available for the company.
Send an email to the Mailbox
1
Attach one invoice or credit note
Attach the document as UBL XML or as PDF. One email makes one document. For more than one invoice, send more than one email.
2
Add the mailbox address
Put the mailbox address in the BCC field (recommended), or in the To or CC field. With BCC, your customer does not see the address.
3
Send the email
The email shows in the Mailbox. Processing of a PDF can take some minutes, because the data is extracted from the PDF.
4
Review and send the draft
When the processing is complete, the email has a
document_id. The document is in state DRAFT. Review it, then send it with POST /api/documents/{document_id}/send.What happens to an email
Selection of the main attachment
The Mailbox uses the content type (MIME type) of each attachment to find the candidates, not the file extension:
For example, a UBL file
invoice.xml with the content type application/xml is a candidate. If your mail program sends the same file with the content type application/x-unknown, the email has no candidate.
The main attachment can be 10 MB at most.
Other attachments
- PDF as main attachment: the PDF and the other attachments with a file type that Peppol permits (rule BR-CL-24: PDF, PNG, JPEG, CSV, XLSX, ODS) become attachments of the document. Other file types, and images that are part of the email body (for example a logo in a signature), are ignored.
- UBL as main attachment: only the UBL is used. Other attachments in the email are not added. Embed the attachments in the UBL itself. See Attachments and PDF.
Conversion and validation
- A UBL file is validated against Peppol BIS Billing 3.0. An invalid UBL makes the email fail.
- A PDF is converted in the same way as in Create documents from PDF. If the extracted data does not make a valid e-invoice, the email fails.
- A successful email makes one document in state
DRAFT. The Mailbox does not send the document through Peppol. You send it yourself.
Email status
The status of an email is not a field in the response. It is derived fromprocessed and error_message. You can filter on it with the status parameter.
The API sets
error_message only when the conversion of the main attachment fails. Some failures occur before the conversion. Then the email stays pending and has no error_message. These are the frequent causes:
- The email has no PDF or UBL candidate (see Selection of the main attachment).
- The main attachment is larger than 10 MB.
- The From address is not in the list of allowed senders of the company.
pending. An email that stays pending for more than some minutes probably has one of these causes. POST /api/mailbox/{inbound_email_id}/reprocess refuses a pending email (409). Correct the cause and send a new email.
List the emails
GET /api/mailbox/ returns the emails of your company, with the newest email first.
Filter by the
processed field. Ignored when status is set. For example, ?status=failed&processed=true returns all failed emails, also the emails with processed false.Inclusive lower limit of the received date, for example
2026-10-01T00:00:00Z. If an email has no received_at, the filter uses created_at.Inclusive upper limit of the received date, for example
2026-10-31T23:59:59Z. If an email has no received_at, the filter uses created_at.Case-insensitive search in the sender email address, the subject, the message ID and the attachment file names. The text can be a part of the value:
?search=inv-2026 finds the attachment invoice-INV-2026-001.pdf.Sort field:
received_at or created_at. With received_at, emails with no received_at come last in both directions, and created_at orders emails with the same received_at.Response
Response fields
Get one email
GET /api/mailbox/{inbound_email_id} returns one email. Use it to poll an email until document_id has a value or error_message has a value.
cURL
Response
404 with {"detail": "Inbound email not found"}.
Download an attachment
GET /api/mailbox/{inbound_email_id}/attachments/{filename} returns the original file from the email. The response body is the binary content, with the Content-Type of the attachment and a Content-Disposition: attachment header.
The filename must be exactly the same as attachments[].filename in the email. URL-encode the file name.
Response
404 in these conditions:
The endpoint gives
500 if the API cannot read the stored original or decode the attachment. Examples of the detail: Failed to retrieve email payload from storage, Failed to decode attachment content.
Retry a failed email
POST /api/mailbox/{inbound_email_id}/reprocess processes a failed email again from the stored original. Use it after you corrected the cause of the failure on your side, or when the failure was temporary (for example a timeout of the PDF conversion). The request has no body.
Response (202 Accepted)
202 Accepted means that the processing started again, not that it is complete. The API clears the previous error_message and processed_at, and the email goes back to pending. Poll GET /api/mailbox/{inbound_email_id} to get the result.
The endpoint refuses the request in these conditions:
Track the result in the document timeline
When an email made a document, the timeline of that document contains two Mailbox events:email_received and email_processed. The id of each event is the ID of the email, and details has the subject and the attachment metadata.
cURL
Response (extract)
Troubleshooting
The email is not in the Mailbox
The email is not in the Mailbox
Make sure that the full mailbox address, with the part after the
+, is in the To, CC or BCC field. An email to an address that does not match a company is not stored in a Mailbox.The email stays pending and has no error message
The email stays pending and has no error message
The processing stopped before the conversion. Make sure that the email has a PDF or UBL attachment with a correct content type, that the main attachment is not larger than 10 MB, and that the From address is in the list of allowed senders of the company (if the company has this list). Then send a new email. See Email status.
The email failed with an invalid UBL message
The email failed with an invalid UBL message
The UBL attachment does not pass the Peppol BIS Billing 3.0 rules. Use
POST /api/validate/ubl to get the rule failures, correct the file and send a new email. See Send UBL documents.The email failed because no valid e-invoice could be made from the PDF
The email failed because no valid e-invoice could be made from the PDF
The data extracted from the PDF does not make a valid invoice (for example, a tax ID or a total is missing). Download the attachment to examine it. You can also convert the PDF with
POST /api/documents/pdf, correct the JSON and create the document with POST /api/documents/. See Create documents from PDF.The wrong attachment was used
The wrong attachment was used
When an email has UBL and PDF files, UBL has precedence. When an email has more than one file of the same type, the selection uses the subject and the file names. Put the full file name of the invoice in the subject, or send one invoice file for each email.
Next Steps
Create documents from PDF
Learn how a PDF is converted into an e-invoice.
Send UBL documents
Send UBL XML that your system already makes.
Document lifecycle and delivery tracking
Follow a document from draft to delivery.
Webhooks
Get a notification when a document is sent.