Skip to main content

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 email itself needs no API call. The Mailbox API is for monitoring: list the emails, read one email, download an attachment and retry a failed email.
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 field bcc_recipient_email.
cURL
Response (extract)
If bcc_recipient_email is null, the Mailbox is not available for the company.
Keep the address private. The part after the + identifies your company, and an email to this address makes a document in your 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 Mailbox counts each text/plain attachment as a UBL candidate, and UBL has precedence over PDF. Thus an email with invoice.pdf and a text file notes.txt (text/plain) does not make a document. Do not attach text files to an email with a PDF invoice.
The main attachment can be 10 MB at most.
Send one invoice file for each email and give it a clear file name, for example invoice-INV-2026-001.pdf. Then the selection is not ambiguous.

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 from processed 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.
An unexpected error before the conversion, for example in the automatic selection of the main attachment, also leaves the email 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.
integer
default:"1"
Page number. Minimum 1.
integer
default:"20"
Number of emails for each page. Minimum 1, maximum 100.
string
Filter by status: pending, success or failed. Has precedence over processed.
boolean
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.
string (date-time)
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.
string (date-time)
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.
string
default:"received_at"
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.
string
default:"desc"
Sort direction: asc or desc.
The example lists the failed emails.
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
An ID that does not exist, or that belongs to a different company, gives 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
The endpoint gives 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)
See Document lifecycle and delivery tracking for the other events and the document states.

Troubleshooting

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 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 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 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.
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.