Skip to content

Receive by email

This guide describes how to receive invoices by email. xTool gives your organisation dedicated mailboxes under Interfaces → Mailbox Configuration. There are two modes:

Mode Purpose Resulting documents
Inbound Suppliers send purchase invoices to you Inbound documents with a receive.email transaction
Outbound You (or an internal process) send invoices into xTool for further sending Outbound documents created like an upload (no receive transaction)

Each mode has its own email address. Personalized outbound addresses use a .outbound tag (for example firma-de@… inbound, firma-de.outbound@… outbound).

You do not upload the file yourself in the web app — you email the attachment to the address for that mode.

How it works

  1. Open Interfaces → Mailbox Configuration and select the Inbound or Outbound tab.
  2. Create a mailbox for that mode and copy the email address.
  3. Share the address (inbound → suppliers; outbound → whoever should feed outbound invoices into xTool).
  4. They send an email with the invoice attached.

  5. xTool checks active mailboxes regularly and processes new messages:

    • Inbound → document under Documents → Inbound, transaction type receive.email.
    • Outbound → document under Documents → Outbound, status path like a normal upload (upload.completed).

xTool checks mailboxes about every 30 minutes. After an email is sent, wait for the next check before looking for the document.

An invoice that arrives with validation errors is still stored (is_valid false). The receive (inbound) or upload (outbound) still completes; notifications may report validation failure separately. See Notifications.

Set up a mailbox

You need permission to manage integrations. See Organisation and users.

  1. Sign in to the xTool web app and select your organisation.
  2. Open Interfaces → Mailbox Configuration.
  3. Choose the Inbound or Outbound tab.

  4. Choose an email address:

    Option When to use
    Personalized Based on your company domain. Example inbound: domain firma.de → firma-de@smtp.invoice-portal.com. Outbound: firma-de.outbound@…. If taken, xTool offers the next free variant.
    Random A unique address that does not include your company name. Outbound random addresses also include the .outbound tag. Always available.

  5. Click Create Email Mailbox (or the inbound/outbound setup button for that tab).

  6. Copy the Email address from the connection details.

The mailbox status should be Active. Use Test Connection if you want to confirm that xTool can reach the mailbox. Configure each mode separately (whitelist, lock/unlock, delete).

Personalized address is not always offered

If the organisation uses a public email provider (for example Gmail, GMX, Yahoo, Web.de, Hotmail, or iCloud), only the random address is available.

Two mailboxes, two addresses

An organisation can have one inbound and one outbound mailbox. They must use different addresses. Do not give suppliers the outbound address if you only want purchase invoices under Documents → Inbound.

Restrict who can send (whitelist)

On each tab under Mailbox Configuration, Sender Whitelist controls which senders xTool accepts for that mode.

Mode Effect
Disabled Emails from any sender are processed.
Enabled Only senders on the list are processed. Others are rejected.

When the whitelist is enabled, enter allowed addresses separated by semicolons. You can use * as a wildcard, for example:

  • ap@supplier.de
  • *@supplier.de — any address at that domain

Rejected senders can be notified if you enable Notify Sender for receive failures. See Notifications.

What to attach

The email must include at least one invoice file:

File Accepted as the invoice
XML XRechnung, UBL, or CII e-invoices
PDF (ZUGFeRD / Factur-X) PDF with an embedded XML invoice
PDF Ordinary PDF without embedded XML

You may also attach supporting files such as CSV, PNG, JPEG, Excel (.xlsx), or ODS. Files embedded inside the invoice XML or ZUGFeRD PDF are stored with the document; loose supporting attachments next to the invoice in the email are currently not stored as document attachments.

Emails without an XML or PDF invoice are rejected (for example an empty message, or only a signature image).

If the invoice is a plain PDF, xTool may use the file name as the document number.

Where to see documents

Mailbox mode Web API / transactions
Inbound Documents → Inbound direction=inbound; transaction type receive.email
Outbound Documents → Outbound direction=outbound; upload status (no receive.email)

See Documents UI, Document model, and Transactions.

Notifications

Configure notifications under Account → Notifications, in Inbound documents:

  • Receiving Completed — a document was created from the email.
  • Receiving Failed — the email was rejected or the document could not be processed / failed validation messaging.

For each event you can set recipient addresses and how the email is delivered (plain message, download link, or files attached). For a failed receive you can also enable Notify Sender, so the person who sent the invoice gets the rejection reason (for example: not on the whitelist, no invoice file, unsupported format).

The notification can include the invoice number and date, sender, a link to the document, the files from the email, and validation errors when the invoice is invalid.

See Notifications.

If documents do not appear

  • Confirm the correct tab (Inbound / Outbound) and that the mailbox status is Active.
  • Confirm senders use the exact address shown for that mode.
  • Wait up to about 30 minutes after the email was sent.
  • If the whitelist is Enabled, check that the sender’s address (or domain) is on the list for that mode.
  • Check that the email has an XML or PDF invoice attached.
  • For inbound: check Account → Notifications for receive-failed messages, and open Documents → Inbound for any document that arrived with validation errors.
  • For outbound: open Documents → Outbound.

← Channels · Send by email · Receive via Peppol