Overview
IncaMail Enterprise Application Integration (EAI) allows organizations to integrate secure IncaMail messaging directly into their business software such as ERP systems, HR platforms, or document management solutions. This enables automated, compliant sending of confidential, personal, or registered messages (e.g. payslips, invoices, or legal notices) without any manual steps from the end user.
There are four main steps to get started: signing up for a subscription, registering your administrator account and the sender account(s) that your business software will use to send messages, and then completing the technical setup by choosing and configuring the integration method that best fits your infrastructure.
This article guides you through each step and explains the available integration methods so you can choose the right approach for your use case.
Prerequisites
Before you begin, make sure the following are in place:
- IncaMail corporate contract: Your organization must be a registered IncaMail corporate customer with a valid contract that includes the EAI option.
- Developer resources: For SOAP and REST API integrations, developers familiar with SOAP or REST in their programming environment are required.
- Firewall access: Depending on the integration method, port 587 (SMTP/TLS Auth) or port 25 (Domain Integration) must not be blocked by your firewall.
- If using Domain Integration: Domain ownership - You must be able to verify ownership of the domain(s) from which messages will be sent.
Step 1 – Register an Account
If you do not already have an IncaMail account, register one first. The email address used during registration will serve as the administrator account.
👉 Register here: https://app.incamail.com/en/register
Note: Each email address that will be used to send messages from your business software must also be individually registered on the IncaMail platform before it can be authorized for use with any EAI integration method.
Step 2 – Sign Up for a Business Subscription
EAI functionality requires an active IncaMail business subscription with the EAI option enabled. A 30-day free trial is available with no commitment required.
👉 Sign up here: https://web.incamail.com/en/e-mail-encryption/incamail-for-the-e-mail-client
Note: Signing up for a trial does not constitute a binding order. You can evaluate the integration during the trial period before deciding whether to proceed.
Step 3 – Choose Your Integration Method
EAI offers four integration methods. The right choice depends on your business software's capabilities and your infrastructure:
| Method | Description | Best for |
|---|---|---|
| SMTP/TLS Auth | IncaMail acts as a standard authenticated SMTP server. Simple to configure in any programming language or software that supports SMTP. | Business software with built-in SMTP sending capability |
| Domain Integration (EAI over MGI) | Sending via your existing corporate mail server using SMTP over TLS/SSL. | Environments where MGI is already in place, or where sent messages need to be archived in mailboxes |
| SOAP API | Three powerful APIs (Send, Read, Admin) for full flexibility, message tracking, decryption of received messages, and account management. | Custom integrations in SAP and other enterprise systems requiring tracking or decryption |
| REST API | Modern REST-based sending with support for large file attachments (up to 1 GB) and delivery tracking. | Web applications and modern development environments |
Step 4 – Complete the Technical Setup
You can find the full technical guide to set up the Enterprise Application Integration here: https://support.incamail.com/hc/article_attachments/23166869784466
SMTP/TLS Auth
IncaMail behaves like a standard SMTP mail transfer agent (MTA). Messages are sent using standard SMTP with TLS authentication, and the delivery type is specified via tags in the subject line.
Server details:
| Production | Integration / Test | |
|---|---|---|
| SMTP Server |
incamail.com (MX lookup) or gw1.incamail.com (static) |
sta.incamail.com (MX lookup) or gw1.sta.incamail.com (static) |
| Port | 25 or 587 | 25 or 587 |
| Authentication | Basic Auth (username = sender email address, password = self-defined during registration) | Same |
| Encryption | STARTTLS (mandatory before sending password) | Same |
Important: STARTTLS must be activated before the password is transmitted. Without TLS, the connection to IncaMail is not protected. The email address used for authentication must match the sender address in the
FROM:header.
Subject line tags for delivery type:
-
<im> <c>— Confidential -
<im> <p>— Personal -
<im> <r>— Registered
Example subject: <im> <c> Salary Slip 12/2024
Domain Integration (EAI over MGI)
This method is used when:
- Your organization already uses IncaMail MGI and a business software additionally needs to send via the same infrastructure.
- Sent messages need to be stored in mailboxes for archiving purposes.
- Your business software already uses a corporate mail server for outbound email.
⚠️ Important — Setup Assistance Required: Unlike the other EAI integration methods, Domain Integration (EAI over MGI) cannot be fully configured via self-service. Because sending is facilitated through your corporate mail server rather than directly via SOAP, TLS Auth, or REST, additional configuration on the IncaMail side is required. Please contact IncaMail Support to initiate the setup: 👉 https://support.incamail.com/hc/en-us/requests/new
For the MGI domain setup itself, refer to the MGI Setup Guide.
Subject line tags and recipient address format:
| Field | Format | Example |
|---|---|---|
| Subject | Prepend delivery type tag | <im> <c> Salary Slip 12/2024 |
| To / CC / BCC | Append .incamail.ch to every recipient address |
john.doe@gmail.com.incamail.ch |
SOAP API
The SOAP API provides three separate APIs for maximum flexibility:
| API | Purpose |
|---|---|
| SOAP Send | Send messages and track delivery status |
| SOAP Read | Decrypt received encrypted IncaMail (SAFE) messages |
| SOAP Admin | Modify corporate customer account data (company name, banner, logo) |
Production endpoints:
| URL | |
|---|---|
| SOAP Send | https://ws.incamail.com/3.0/ |
| SOAP Read | https://wsread.incamail.com/3.0/IncaMailReadService |
| SOAP Admin | https://wsmgmt.incamail.com/IncaMailAdminService/IncaMailAdminPort |
Test / Integration endpoints:
| URL | |
|---|---|
| SOAP Send | https://ws.sta.incamail.com/3.0/ |
| SOAP Read | https://wsread.sta.incamail.com/3.0/IncaMailReadService |
| SOAP Admin | https://wsmgmt.sta.incamail.com/IncaMailAdminService/IncaMailAdminPort |
Important: Always include the trailing
/in endpoint URLs where indicated. Always use the integration platform during development and testing — switch to the production platform for live usage only.
Authentication: Basic Authentication (Preemptive) via HTTPS. Username = registered IncaMail email address, password = self-defined during registration.
SSL Certificate: Some systems (e.g. SAP) require the IncaMail server root SSL certificate to be registered. Download the SwissSign Gold CA – G2 certificate here:
- PEM:
https://swisssign.net/cgi-bin/authority/download/5B257B96A465517EB839F3C078665EE83AE7F0EE.pem
For detailed SOAP request examples, WSDL definitions, and SAP-specific setup instructions, refer to the full EAI Integration Guide: 👉 https://support.incamail.com/hc/article_attachments/23166869784466
REST API
The REST Send API offers a modern, lightweight alternative for sending messages and tracking delivery status, with built-in support for large file attachments up to 1 GB.
Base URLs:
| URL | |
|---|---|
| Production | https://incamail.com/xapi/send/v1/ |
| Integration / Test | https://sta.incamail.com/xapi/send/v1/ |
Key endpoints:
| Endpoint | Method | Purpose |
|---|---|---|
/ping |
GET | Connection check |
/message/send |
POST | Send an IncaMail message |
/message/prepareFile |
POST | Pre-upload a large file attachment (up to 1 GB) |
/sentMessages/getDeliveryState |
POST | Track delivery status by message ID |
Authentication: Basic Auth (email address + password).
Authorization: Each sender email address must be explicitly authorized by IncaMail Support before use. Contact: business@incamail.ch and provide the sender email addresses and the platform (integration or production) to be used.
OpenAPI documentation: https://incamail.com/apidef/restsend/index.html
For detailed REST request examples and Postman setup instructions, refer to the full EAI Integration Guide: 👉 https://support.incamail.com/hc/article_attachments/23166869784466
Delivery Types
Across all integration methods, the following delivery types are available:
| Delivery Type | SOAP/REST value | Subject tag | Description |
|---|---|---|---|
| Confidential | enc |
<im> <c> |
Encrypted if recipient is not on a TLS domain; signed and unencrypted for MGI recipients |
| Personal | encPersonal |
<im> <p> |
Always encrypted, even for MGI recipients |
| Registered | reco |
<im> <r> |
Legally verifiable with delivery and acceptance receipt |
| Signed only | plain_signed |
— | Signed but not encrypted (REST API only) |
Understanding Message Encryption (SAFE Format)
IncaMail uses the patented SAFE (Secure Attached File Encryption) format to transport encrypted messages. Depending on the recipient's setup, one of the following delivery methods is used:
- TLS delivery: For recipients with MGI domain integration, messages are delivered encrypted over TLS directly to their mail gateway.
-
SAFE attachment: For all other recipients, the entire message is encrypted into a SAFE attachment (
IncaMail.html). The recipient decrypts the message via the IncaMail web interface, mobile app, or a SOAP Read integration. - Hybrid: Same as SAFE, but with an added "Read" button for faster access.
The sending application does not need to handle encryption — IncaMail manages this automatically based on the recipient's setup.
Frequently Asked Questions
Do all sender accounts need to be individually registered? Yes. Every email address used to send messages via any EAI method must be individually registered on the IncaMail platform and authorized for the relevant integration method.
Can I use the SOAP API without a separate EAI contract? No. A valid IncaMail corporate contract with the EAI option must be in place and configured by IncaMail before the API can be used.
Can I use multiple integration methods in parallel? Yes. For example, an organization might use SOAP Send for automated payslip delivery and Domain Integration for messages sent manually via Outlook — both can run simultaneously under the same contract.
How many parallel SOAP threads can I use? We recommend a maximum of four parallel threads for sending SOAP requests to the IncaMail server to avoid performance issues.
Where can I test without affecting production? Use the integration/test platform (sta.incamail.com / ws.sta.incamail.com) during development. Always switch to the production endpoints before going live.