ePost (digital letter)

ePost Service Ltd, a subsidiary of Swiss Post, operates the ePost Communication Platform. Its public API accepts a document once. ePost then decides per recipient whether to deliver it digitally to the ePost Digital Letterbox, by email, SMS, eBill, or physically as a printed letter. A document generated in primedocs can be handed over to this interface directly through Output Management.

Customer-specific configuration

This integration is a template configuration. It requires a contract with ePost and an allow-listed target URL.

How it works

1. The template is generated in primedocs as usual.
2. An output of the template converts the document to PDF and sends it together with the recipient and delivery metadata to the ePost API.
3. ePost performs identity matching: the submitted recipient credentials (address, email, mobile number) are checked against ePost to determine whether the recipient has an ePost Digital Letterbox.
4. Depending on the match and the permitted channels, ePost delivers digitally or hands the item to a print service provider for physical dispatch.

Delivery channels

A single API call serves all channels. The deliveryChannelPreferences metadata field controls which ones are permitted.

Channel	Value	Note
ePost Digital Letterbox	DIGITAL	Digital delivery to the ePost app or web app.
Email	EMAIL	Sent from an ePost sender domain.
SMS	SMS	Short message, for plain text messages without a PDF only.
eBill	EBILL	Invoices in e-banking. Requires PDF/A-3 and additional metadata.
Physical letter	PHYSICAL	Printing and dispatch through an ePost print partner.
Automatic triage	AUTO	ePost selects the cheapest available channel.

tip

Prefer AUTO

ePost recommends AUTO over an explicit channel list. This activates the platform's triage logic: digital where the recipient is reachable, otherwise the next best channel.

The ePost interface

The authoritative reference for endpoints, metadata fields, and environments is the ePost Developer Zone. Only the following points matter for the configuration in primedocs.

Authentication. The API uses OAuth 2.0 with the resource owner password grant: the username, password, tenant_id, and company_id of a technical account are exchanged for an access_token at the token endpoint (POST /core/latest/token, application/x-www-form-urlencoded). The token is valid for ten minutes and is therefore fetched immediately before each submission rather than cached.

Submission. The document is sent as multipart/form-data to POST /epost/v2/synchronous-deliveries. The request consists of two kinds of parts:

Part	Content
metadata	JSON with a fileMetadata array (one entry per file).
files	The PDF file. The part is named files (plural) even for a single file and may occur several times.

Metadata and files are matched through fileName: the value must be exactly the file name of the corresponding files part.

Requirements on the template

For the item to be processed, the generated PDF must meet these requirements (they concern the layout of the template, not the configuration):

Requirement	Details
Page format	For physical dispatch, all pages in A4 portrait. Landscape or other formats cannot be processed.
Address position	The recipient address must appear at the position specified by ePost. Alternatively, a cover sheet can be prepended.
Address consistency	The address in the PDF must be identical to the address in the metadata. Otherwise, delivery problems or incorrect franking may occur.

Integration from primedocs

The submission is configured as an InvokeUrl command in the template's Output Management: step 1 fetches the access token, step 2 sends metadata and document as multipart/form-data.

Prerequisite: allow-list the target URL

InvokeUrl only calls approved addresses. Add the base URL in the DataSourceAdminApp under Connect Settings → InvokeUrl - Configuration:

<CommandConfig>
  <Url startsWith="https://api.epost.ch" />
</CommandConfig>

Without this entry, the command fails.

Configuring the output

The file name and the metadata are assembled in fields of the output. The <Fields> sit inside the <DesktopOutput>, not in a configuration of their own. Locally declared fields are referenced by their bare name ($("EPostFileName"), field-Value="EPostMetadata"), while global fields keep their prefix (Forms.…, Data.…).

JSON.stringify handles the escaping when assembling the metadata. This is important because recipient names and addresses may contain quotation marks, umlauts, or backslashes.

<OutputConfiguration>
  <DesktopOutput Name="Send as digital letter"
                 Tooltip="Submits the document to ePost">

    <Fields>
      <!-- Unique file name per execution -->
      <Text Name="EPostFileName">
        <Code><![CDATA[
          function main() {
            return "Letter_" + $.util.generateGuid() + ".pdf";
          }
        ]]></Code>
      </Text>

      <Text Name="EPostMetadata">
        <Code><![CDATA[
          function main() {
            const recipient = $("Forms.Recipient");
            return JSON.stringify({
              costCenter: "Customer correspondence",
              fileMetadata: [{
                fileName: $("EPostFileName"),
                documentTitle: $("Forms.Subject"),
                documentTypes: ["message"],
                documentReferenceDate: new Date().toISOString().substring(0, 10),
                senderName: "Example Ltd",
                deliveryChannelPreferences: ["AUTO"],
                allCredentialShouldMatch: false,
                senderCaseId: $("Forms.CaseNumber"),
                recipients: [{
                  senderUserId: recipient.CustomerNo,
                  unhashedCredentials: {
                    minimumLevelOfTrust: "BRONZE",
                    firstName: recipient.FirstName,
                    lastName: recipient.LastName,
                    street: recipient.Street,
                    streetNumber: recipient.StreetNumber,
                    zipCode: recipient.ZipCode,
                    city: recipient.City,
                    email: recipient.Email
                  }
                }]
              }]
            });
          }
        ]]></Code>
      </Text>
    </Fields>

    <Commands>
      <InvokeUrl>
        <!-- Step 1: fetch the access token (valid for 10 minutes) -->
        <Step>
          <Request Method="Post">
            <Url>https://api.epost.ch/core/latest/token</Url>
            <Header Name="Content-Type" Value="application/x-www-form-urlencoded" />
            <Body>grant_type=password&amp;username=TECHNICAL_ACCOUNT&amp;password=PASSWORD&amp;tenant_id=TENANT_ID&amp;company_id=COMPANY_ID</Body>
          </Request>
          <Response>
            <Property Name="AccessToken" JsonPath="$.access_token" />
          </Response>
        </Step>

        <!-- Step 2: submit document and metadata -->
        <Step>
          <MultipartFormDataRequest>
            <Url>https://api.epost.ch/epost/v2/synchronous-deliveries</Url>
            <Header Name="Authorization" Value="Bearer {AccessToken}" />
            <FormData Name="metadata" field-Value="EPostMetadata" />
            <File Name="files"
                  field-FileName="EPostFileName"
                  ContentType="application/pdf">
              <Document Conversion="Pdf" />
            </File>
          </MultipartFormDataRequest>
        </Step>
      </InvokeUrl>
    </Commands>
  </DesktopOutput>
</OutputConfiguration>

The key points of the configuration:

Element	Note
<Fields> in <DesktopOutput>	The output's fields live in the output itself and are referenced without a prefix.
<FormData Name="metadata" …>	The part is named metadata. fileMetadata is only the key inside the JSON, not the form field name.
<File Name="files" …>	The file part is named files (plural), even for a single file.
field-FileName	Points to the same field as fileName in the JSON so that both values match.
<Document Conversion="Pdf" />	Forces the PDF conversion of the Word template. If the template already produces a PDF, the attribute is omitted.
{AccessToken}	Value from the Response of step 1.

Field names

The names under Forms.… and the properties of the recipient object depend on the data source and are defined per use case.

Use in Web and through the API

The same InvokeUrl block works unchanged in a WebOutput for primedocs Web and the Office Web Add-ins, and in an OnSuccess block of the Connect/Document API for server-side generation. InvokeUrl is one of the commands available in all three contexts.

Limitations

Credentials in plain text

ePost uses the resource owner password grant with a technical account. The primedocs Connected Services support only the authorization code flow with interactive sign-in per user and are therefore not an option. Username and password therefore appear in plain text in the template configuration.

Credentials in plain text

For production use, use a dedicated technical account with minimal permissions, rotate the password regularly, and restrict access to the template configuration accordingly.

PDF/A-3 for eBill

The primedocs PDF conversion produces PDF/A-1B, both server-side and through Word (Conversion="PdfViaOffice"). This satisfies the ePost PDF/A requirement for every channel except eBill. The eBill channel requires PDF/A-3, which the conversion does not produce.

Onboarding with ePost

Access, environments, and base URLs are agreed with ePost (support.enterprise@epostservice.ch). For the physical channel, the address position and print profile are tested together with ePost before going live.

Further reading

• ePost Developer Zone: API reference, metadata, and examples
• Der Digitale Brief: scope of service and pricing
• Output Management: outputs in templates
• After document generation (commands): reference for InvokeUrl