> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valedo.uniwave.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Publishing and test deployment

> Deploy Valedo as a custom Outlook add-in for testing, publish it to Microsoft Marketplace, and see where it stands against Microsoft's requirements.

> [!WARNING]
>
> **Status: the publishing path is not ready.** Checked against the repository on 2026-10-31: there is no add-in manifest, no Marketplace landing page (Resolve and Activate), no usage emitter, no add-in sign-in code, and no way to create a test tenant. The [readiness review](#readiness-review) lists every gap with its evidence. The procedures below follow Microsoft Learn and describe what to do once those pieces exist.

This page is for engineers and Publisher staff. It owns the publishing procedure and the readiness review. The Partner Center field values (plan, meter dimension, landing page, webhook) live in [Marketplace and tenant setup](https://docs.valedo.uniwave.ai/publisher-guide/marketplace-setup.md) and are not repeated here. The design decisions behind them stay in README §2, §4.8 and §4.10.

## Stages

| Stage | Who | Where it runs | Needs |
| - | - | - | - |
| 1. Sideload | One developer | The developer's own mailbox | Manifest, HTTPS dev host |
| 2. Custom upload | A Valedo admin of a pilot tenant | Pilot users in that tenant | Manifest or app package, Integrated apps access |
| 3. Marketplace preview | The preview audience | A separate DEV offer | Offer in Partner Center, landing page, webhook |
| 4. Restricted listing | Customer admins | Admin-deployed with a flight code | Published offer and add-in listing |
| 5. Unrestricted listing | Anyone | Event-based activation without admin deployment | Microsoft 365 Certification |

Launch with stage 4 (README §4.10). Stage 5 is a later step and does not block launch.

## Prerequisites for any test

* **HTTPS host for the add-in files.** Marketplace and Office on the web require HTTPS. README §4.1 plans the assets under `/addin/*` on Valedo.API host (`dev.valedo.uniwave.ai` in dev). Confirm where the dev assets are actually served before you build the manifest.
* **The dev `Valedo` app ID** from [Entra app registrations](https://docs.valedo.uniwave.ai/developers/entra-apps.md). The add-in sign-in uses its identifier URI.
* **A work mailbox in a test tenant.** For sideloading in a mailbox, Learn requires the Exchange **My Custom Apps** role for that account.
* **An onboarded test tenant.** The signature endpoint answers `tenant_not_onboarded` (403) and the add-in inserts nothing until the tenant is in the registry. I found no endpoint, job or documented seed step that creates a tenant document: the Publisher API only lists and reads tenants, and README §4.8 assigns provisioning to the landing page, which is not built. Until it is, a test tenant has to be written directly into the `tenants` container by an engineer. This is a gap to close first, not a step to improvise.

## Create the manifest

The repository has no manifest (`src/addin` holds only `src/`, `tests/` and build files). Create one before any test. Learn describes two manifest types; which one Valedo ships is an open decision (README §13, item 11).

| | Add-in only manifest (XML) | Unified manifest (JSON in an app package) |
| - | - | - |
| Sideload in Outlook on the web, Windows (new, classic) and Mac | Yes, **Add from File** | Through Agents Toolkit or `office-addin-debugging`; not on Outlook for Mac |
| Outlook on mobile | Supported | Not supported |
| Admin center upload, **App type** | Office Add-in | Teams app |
| Admin center add-in portal | Supported | Not supported (integrated apps portal only) |

Sources: [Sideload Outlook add-ins](https://learn.microsoft.com/office/dev/add-ins/outlook/sideload-outlook-add-ins-for-testing), [Sideload with the unified manifest](https://learn.microsoft.com/office/dev/add-ins/testing/sideload-add-in-with-unified-manifest), [Test on mobile](https://learn.microsoft.com/office/dev/add-ins/outlook/test-mobile-add-ins), [Activate add-ins with events](https://learn.microsoft.com/office/dev/add-ins/develop/event-based-activation).

Whichever type you choose, the manifest must:

* carry a unique, valid GUID as the add-in ID and HTTPS URLs for all code and content files;
* include a support URL (Marketplace submission requires it) and the PNG icons listed in `docs/brand.md` (16, 32, 64, 80, 128);
* subscribe to `OnNewMessageCompose` only. Adding events later makes every customer admin consent again in Integrated apps, so keep the event set stable;
* for the add-in only type, leave out the `CustomPane` extension point and the `ItemSend` event (Marketplace policy 1120.4).

Also create `.well-known/microsoft-officeaddins-allowed.json` listing the exact event runtime URL (README §4.10). It is not in the repository either.

## Test as a custom add-in

### Sideload in one mailbox (add-in only manifest)

1. Open `https://aka.ms/olksideload`. Outlook on the web opens and the **Add-Ins for Outlook** dialog appears.
2. Select **My add-ins**, then under **Custom Addins** select **Add a custom add-in** and **Add from File**. **Add from URL** is no longer offered; download the manifest and add the file.
3. Accept the prompts. In classic Outlook on Windows it can take up to 24 hours for the add-in to appear.

For a unified manifest, build the app package and use `atk install --file-path <package.zip>` or `npx office-addin-debugging start <manifest> desktop`, and stop the session the same way. Outlook on mobile cannot be sideloaded directly; sideload on the web or desktop first, and only an add-in only manifest is supported on mobile.

### Upload to a pilot group (Microsoft 365 admin center)

1. Sign in as an admin of the test tenant: **Settings → Integrated apps → Upload custom apps**.
2. Set **App type** to **Office Add-in** and upload the XML manifest, or to **Teams app** and upload the unified package.
3. Choose **Just me** or a **pilot group**, not **Everyone**.
4. In **App Permissions and Capabilities**, check the event list shows `OnNewMessageCompose` and accept it.
5. Deploy. A green check means deployed, but the add-in can take 24 to 72 hours to appear. Users may need to restart Outlook.

Event-based add-ins work only when deployed by an admin (or from an unrestricted listing). Any later manifest change that adds events or permissions blocks users until the admin accepts the update. Source: [Deploy Office Add-ins in the admin center](https://learn.microsoft.com/microsoft-365/admin/manage/manage-deployment-of-add-ins).

### What to check

* A new message gets the signature of the rule that matches the sender; reply and forward follow `appliesTo`.
* A body that already starts with the `valedo-signature:` marker is left alone.
* An unlicensed or unknown tenant inserts nothing, and the task pane explains why. The event handler still completes.
* It works in Outlook on the web (modern), new Outlook and classic Outlook. Outlook on the web (modern) support is a Marketplace rule.
* The handler finishes well inside the roughly 300-second event window and calls `event.completed()` on every path.

## Publish to Microsoft Marketplace

Order matters. Steps 1 to 3 are cheap and block everything after them.

1. **Publisher account.** Partner Center commercial marketplace profile with legal, tax and payout details and contacts. Standard Partner Center step; not re-verified here.
2. **Domain and publisher verification.** Verify the domain and complete publisher verification for the `Valedo` app ([steps](https://docs.valedo.uniwave.ai/publisher-guide/marketplace-setup.md)). Publisher verification is also a prerequisite of Microsoft 365 Certification.
3. **Pricing decisions.** README §13 items 1 to 3 (20 or 40 EUR base fee, billing basis, which mailboxes count). The pricing model cannot change after publishing.
4. **Create a separate DEV offer first.** Learn recommends it. Test with nominal amounts in preview and **never press Go live on the DEV offer**, which would publish it to the storefront. Test purchases are billed; a purchase cancelled within 72 hours is refunded on the next month's invoice.
5. **Configure the offer.** Flat rate, one plan, `additional_mailbox` meter, 14-day trial, technical configuration: values in [Marketplace and tenant setup](https://docs.valedo.uniwave.ai/publisher-guide/marketplace-setup.md). Landing page and webhook must run 24/7 and carry no `#` or secrets in the URL.
6. **Fill the listing** (table below).
7. **Link the add-in.** Enter the `Valedo` app ID under Microsoft 365 integration and link the add-in listing. Learn describes linking them as a single SaaS offering. Learn's Teams guidance publishes the app before creating the SaaS offer; confirm the order for an Outlook add-in in Partner Center.
8. **Write the certification notes** (below), then **submit**. After automated validation the offer reaches **Publisher signoff** and preview links appear under **Go live**.
9. **Test end to end in preview** with the preview audience: purchase, landing page, activation, each webhook event (`Subscribe`, `ChangePlan`, `ChangeQuantity`, `Renew`, `Suspend`, `Reinstate`, `Unsubscribe`), plan change, cancellation and metering events, including duplicates and an instant cancel.
10. **Go live with the production offer**, as a restricted add-in listing with a flight code. Admins deploy the add-in from Integrated apps.
11. **Later: attestation and certification.** Complete Publisher Attestation (available for Outlook and SaaS, valid one year, renewed yearly), then Microsoft 365 Certification (evidence within 60 days of the initial approval). After certification, request an unrestricted listing with the form at `https://aka.ms/AutoLaunchForEndUser`.

### Listing fields

| Field | Rule | Valedo value |
| - | - | - |
| Name, summary, description | 200 characters, 100 characters, 5,000 characters | To write. The description must say what the add-in inserts and when |
| Getting started instructions | Required for transactable offers, up to 3,000 characters | To write; link the [customer admin guide](https://docs.valedo.uniwave.ai/admin-guide/get-started.md) |
| Privacy policy link | Valid `https` URL | `/privacy/` on the public site; draft pending legal review (README §9) |
| Terms of use | Customers accept before they try | `/terms/` on the public site; draft |
| Support contact and support URL | Name, phone, email, public URL; URL must differ from the help URL | Email and phone are in `src/web-site/src/data/site.ts`; a public support URL is not confirmed |
| Engineering contact | Name, phone, email; not shown to customers | Not recorded in the repository |
| Logos | PNG, large 216 to 350 px | Export from the brand SVGs (docs/brand.md) |

Sources: [Plan a SaaS offer](https://learn.microsoft.com/partner-center/marketplace-offers/plan-saas-offer), [Listing details](https://learn.microsoft.com/partner-center/marketplace-offers/create-new-saas-offer-listing), [Listing guidelines](https://learn.microsoft.com/partner-center/marketplace-offers/marketplace-criteria-content-validation).

### Certification notes

Put these in **Notes for certification** (policy 1120 and 1120.4, [certification policies](https://learn.microsoft.com/legal/marketplace/certification-policies)):

* How to configure and test the `OnNewMessageCompose` auto-launch scenario, including a test tenant that is already onboarded and a reviewer account.
* A disclosure in the offer description of what is inserted and when, for example "The tenant's signature is inserted when a user starts a new message, reply or forward."
* How the add-in uses single sign-on, which functions use it, and the fallback method. Offers with SSO must include a fallback authentication method.
* Confirmation that the add-in supports Outlook on the web (modern).

### After go-live

Raise the manifest version for every Marketplace update. Adding events, permissions or supported Office applications triggers admin consent for existing deployments. Renew Publisher Attestation every year or its status is revoked.

## Readiness review

Reviewed on 2026-10-31 against Microsoft Learn (links above and in the sources list) and the repository at the head of `develop`. **Verdict: Valedo does not meet the requirements for a transactable SaaS offer yet.** Status values: **Met**, **Partly**, **Not met**, **Not verified** (cannot be shown from the repository).

| Requirement | Status | Evidence |
| - | - | - |
| Landing page runs 24/7, signs the buyer in with Entra, calls Resolve and then Activate | Not met | `marketplace/landing` appears only in docs; no route in `src/web-admin`; README §4.8 lists Resolve, Activate and provisioning as not yet built |
| Free trial prerequisites: Fulfillment APIs, landing page, webhook, Entra SSO | Not met | Depends on the landing page |
| Connection webhook runs 24/7, validates the caller, answers fast, confirms with Get Operation | Met in code, not verified live | `MarketplaceEndpoints.cs`, `MarketplaceWebhookAuthentication.cs`, Worker `MarketplaceEventProcessor`; README §4.7 marks the identity chain "not yet verified end to end" |
| `ChangeQuantity` rejected within 10 seconds, `ChangePlan` auto-accepted | Met | README §4.8; Learn allows a 4xx reply for `ChangeQuantity` and auto-accepts `ChangePlan` without a reply |
| Entra tenant ID and application ID for technical configuration | Met | [Entra app registrations](https://docs.valedo.uniwave.ai/developers/entra-apps.md) |
| Metered billing: usage events for `additional_mailbox`, counted and reported | Not met | No match for `additional_mailbox`, `usageEvent` or `UsageReport` in `src`; milestone M6 in README §12 |
| Final prices and billing basis | Not met | README §13 items 1 to 3 are open |
| Add-in manifest with GUID, HTTPS URLs, support URL, icons | Not met | No manifest is tracked in git |
| Allowed-origins file `microsoft-officeaddins-allowed.json` | Not met | Not in the repository |
| Event runtime always calls `event.completed()` | Met | `src/addin/src/commands.ts` |
| Add-in sign-in with a fallback (policy 1120) | Not met | No sign-in code in `src/addin`; README §4.7 Spike |
| Event-based disclosure and test notes (policy 1120.4) | Not met | No listing text or notes written |
| Outlook on the web (modern) support | Not verified | Only unit tests in `src/addin/tests` |
| Privacy policy and terms URLs | Partly | Drafts on the public site, pending legal review (README §9); the site is not in Bicep yet (README §4.7) |
| Support contact, support URL, engineering contact | Partly | Support email and phone in `site.ts`; no public support URL or engineering contact recorded |
| Publisher verification of the `Valedo` app | Not verified | Manual step; `termsOfServiceUrl` and `privacyStatementUrl` default to empty in the Entra parameters |
| HTTPS add-in host and public hostnames | Partly | Custom hostnames are optional Bicep parameters set per environment; not verified live |
| Test tenant can be onboarded | Not met | No endpoint, job or seed creates a tenant (see prerequisites) |
| Publisher Attestation | Not started | Optional for launch; prerequisite of certification |
| Microsoft 365 Certification and unrestricted listing | Not started | Not needed for a restricted listing with admin deployment |

### Blockers, in order

1. Build the landing page: Entra sign-in, Resolve, tenant provisioning, Activate. It also unblocks trials, tenant onboarding for tests and the end-to-end preview.
2. Create the add-in manifest, the allowed-origins file and the add-in sign-in, and decide the manifest type (README §13, item 11).
3. Build the mailbox counter and usage emitter (README §4.9) and validate them on a preview plan.
4. Close the pricing questions and finalise the legal texts.
5. Create the DEV offer, run the preview test, then write the listing and certification notes.

## Sources

* [Plan a SaaS offer](https://learn.microsoft.com/partner-center/marketplace-offers/plan-saas-offer), [Technical configuration](https://learn.microsoft.com/partner-center/marketplace-offers/create-new-saas-offer-technical), [Test and publish a SaaS offer](https://learn.microsoft.com/partner-center/marketplace-offers/test-publish-saas-offer)
* [Build the landing page](https://learn.microsoft.com/partner-center/marketplace-offers/azure-ad-transactable-saas-landing-page), [Webhook](https://learn.microsoft.com/partner-center/marketplace-offers/pc-saas-fulfillment-webhook), [SaaS free trials](https://learn.microsoft.com/partner-center/marketplace-offers/saas-free-trials)
* [Listing options for event-based add-ins](https://learn.microsoft.com/office/dev/add-ins/publish/autolaunch-store-options), [Office Add-ins manifest](https://learn.microsoft.com/office/dev/add-ins/develop/add-in-manifests)
* [Publisher Attestation](https://learn.microsoft.com/microsoft-365-app-certification/docs/attestation), [Microsoft 365 Certification](https://learn.microsoft.com/microsoft-365-app-certification/docs/certification)

Admin deployment as shown in Microsoft Learn (source: [Deploy Office Add-ins in the Microsoft 365 admin center](https://learn.microsoft.com/microsoft-365/admin/manage/manage-deployment-of-add-ins)):

![Deploy New Add-in button in the Microsoft 365 admin center](https://learn.microsoft.com/microsoft-365/media/deployaddin.png)

![Choosing users and groups for add-in deployment in the Microsoft 365 admin center](https://learn.microsoft.com/microsoft-365/media/selectusers.png)

Learn notes that the add-in portal path shown above supports only add-ins that use the add-in only manifest. Add-ins that use the Microsoft 365 unified manifest deploy from the integrated apps portal.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.