Connect Cleo Integration Cloud: exchange EDI files through partner mailboxes

Fill in your Cleo instance address and the mailbox username and password your Cleo administrator issued, test the sign-in, map each partner, activate — EDI files flow in and out through the partner mailbox.

The Cleo connector exchanges EDI files with your trading partners through a partner mailbox in your Cleo Integration Cloud instance: new files arrive in the mailbox download folder and become orders, and outbound files such as advance ship notices and invoices are uploaded back through the mailbox. This connection does not use an API key pair — there is no Client ID to look for in Cleo. You sign in with your instance address and a mailbox account instead, exactly as described below.

Prerequisites#

• A Cleo Integration Cloud instance you can sign in to, and its address — the same address you use to open Cleo Integration Cloud or Harmony in your browser.
• A partner mailbox set up in that instance for the partners you will exchange files with. The mailbox username and password are issued by your own Cleo administrator when the partner mailbox is set up.
• At least one EDI trading partner whose files go through that mailbox — for example purchase orders coming in, and advance ship notices and invoices going back out.
• One thing to confirm with your Cleo administrator before you start: whether your instance has API Key checking turned on for API calls. Only if it does will you need an API Key at all — most instances do not, and most people leave that field empty.

Get your credentials#

1. Write down your Cleo instance address. It is the address you sign in to Cleo Integration Cloud or Harmony with, for example https://mycompany.cleointegration.com. This becomes the Base URL in the next step — it is required, and it must be your own instance, not a shared or example address.
2. Ask your Cleo administrator for the mailbox username and password for the partner mailbox. They were issued together when the mailbox was set up, and this is the account the connection uses to sign in and exchange files — it is a mailbox account inside your instance, not your personal sign-in unless your administrator made them the same.
3. If the password is lost, do not guess at it: your Cleo administrator resets the mailbox password inside your Cleo instance, and you then use the new password. There is no separate password recovery page for this connection outside the instance.
4. Only if your administrator confirms your instance requires an API Key for API calls: ask them for that API Key as well and keep it with the mailbox credentials. If your instance does not require one, you need nothing more — do not go looking for a Client ID or Client Secret, because this connection does not use them.

Fill it into Integration#

1. Open Integration → Connector Marketplace → Cleo → New connection.
2. Base URL: your Cleo instance address, for example https://mycompany.cleointegration.com. This field is required. Copy it exactly as you use it to sign in — a wrong address means the test in the next step has nowhere to sign in to.
3. Mailbox Username: the mailbox username your Cleo administrator issued when the partner mailbox was set up. Fill in the mailbox account itself, not a personal email address.
4. Mailbox Password: the password issued together with that username. It is encrypted at rest and never echoed back. If you later reset this password inside your Cleo instance, update it here as well, or the connection will stop signing in.
5. API Key (optional): leave this field empty unless your instance has API Key checking turned on for API calls. Only in that case, paste the API Key your administrator gave you. Leaving it empty is the normal case for most instances — an empty field here does not make the connection incomplete.

Test the connection#

Click Test connection. The test signs in to the Base URL with the mailbox username and password and exchanges them for a sign-in token. A pass means one thing only: the instance address is reachable and that mailbox account can sign in. The test does not download or upload any mailbox files, and it does not check your download and upload folders — so a passing test does not by itself mean EDI files can already flow. Folder and partner setup are covered in the next section, and the FAQ below explains what to check if sign-in works but files do not move.

Mapping / pick a template#

Cleo works by file exchange, so mapping is set up per trading partner around that partner’s mailbox folders. For each partner, pick that partner’s template and check two directions: inbound files pulled from the mailbox download folder — for example a purchase order file (850) — should land as a standard order with the order number, lines, quantities, and ship-to details in the right places; and outbound results — the advance ship notice (856) and the invoice (810) built from fulfillment — should be written in the file format that partner expects and placed for upload through the mailbox. Also confirm the download folder for new inbound files and the upload folder for outbound files are set up in the EDI connection settings for that partner: those folders are separate from the four credential fields, and a partner whose folders or mapping are missing has nowhere for its files to land, even when the test passes. Check the mapping preview with one real file from each partner before activating.

Activate#

After activation, Integration pulls new files from the partner mailbox download folder on the schedule you set, turns order files into orders, and uploads outbound files — advance ship notices and invoices — back through the mailbox for delivery to each partner. Only partners with their folders and mapping set up will flow; a partner that was skipped stays silent until its setup is finished. Watch the first files for each partner in Runs / Logs before trusting the exchange unattended.

FAQ#

Test fails: sign-in is rejected

The mailbox username or password on the connection does not match the mailbox account in your Cleo instance, or the password was reset in the instance after you filled it in here. The test only gets as far as signing in, so a rejection at this step is always about the address or the mailbox account itself — not about folders or mapping, which the test never reaches.

Check the Base URL first and make sure it is your own instance address, exactly as you use it to sign in. Then ask your Cleo administrator to confirm the mailbox username, and to reset the mailbox password inside the instance if it may have changed. Paste the current password into the connection, save, and test again.

I cannot find a Client ID, and the API Key field confuses me

There is nothing wrong with your Cleo setup — this connection simply does not have a Client ID. Cleo uses an instance sign-in here instead of an API key pair, so no Client ID or Client Secret is ever issued for it. The API Key field is a separate, conditional extra: it only applies when an instance has API Key checking turned on, which most instances do not.

Stop looking for a Client ID and fill in only the instance address and the mailbox username and password. Leave the API Key field empty, unless your Cleo administrator confirms your instance requires an API Key — in that case, ask them for the key and paste it in. Then test the connection.

Test passes, but no EDI files arrive from a partner

Sign-in works, so the address and mailbox account are fine. The gap is after sign-in: the test never touches mailbox files or folders, so a partner can still be missing its download folder setup, its upload folder setup, or its mapping — and without those, its files have nowhere to be picked up from and never become orders.

Ask your Cleo administrator to confirm the partner mailbox is receiving that partner’s files, then open the EDI connection settings for that partner and check the download folder for new files and the upload folder for outbound files are both set up. Finish that partner’s mapping in the Mapping section above, check it with one real file, and watch Runs / Logs for the partner’s next file.

Orders come in, but ASN and invoice files do not reach the partner

Inbound is working, so the mailbox and its download side are fine. The gap is on the outbound side of that partner’s setup: its upload folder or its outbound mapping for the advance ship notice (856) and invoice (810) was never finished, so the fulfilled results have no file to travel back in.

Open that partner’s EDI connection settings and mapping, and finish the outbound side: the upload folder, plus the 856 and 810 mappings in the file format that partner expects. Check the mapping preview with one fulfilled order, then watch Runs / Logs for the next outbound file to that partner.