Overview
What is its Purpose?
This Connection enables integration steps running on Apinizer to securely access SMTP servers.
Provides manageability from a single configuration point in warning, alarm, notification, or bulk email scenarios.
Ensures compatibility with different service providers thanks to advanced parameters such as TLS, authentication, and custom SMTP headers.
Reduces repetitive definitions in Development/Test/Production distinctions thanks to environment-based settings.
Working Principle
When SMTP type Connection is requested from within Integration Flow or Connector, the system reads configured connection parameters.
Email Connections work with lightweight sessions opened per request; pool is disabled but worker queues queue concurrent requests.
Authentication is performed with username/password if Auth toggle is on, otherwise with anonymous SMTP access.
MIME messages and additional headers are sent via SMTP with TLS/STARTTLS support.
After the operation is completed, session is closed and worker returns to clean state for new requests.
In case of connection error, timeout, or authentication error, details are written to Apinizer logs, error message and recommended actions are notified to the user.
Usage Areas
Automatic email notifications for system events or monitoring alarms
Secure mailboxes that send verification codes from identity providers
Outgoing communication scenarios with PDF attachments such as invoices, receipts, or reports
Sharing periodic status/health reports via Scheduled Jobs
Technical Features and Capabilities
Basic Features
Upgrades SMTP sessions to TLS with enableStartTls toggle.
When auth is active, username/password becomes mandatory and credential verification is performed.
Sender address to be used in all messages is centrally defined with from field.
Ability to define separate connection parameters for each environment (Development, Test, Production).
Making Connection active or passive (enable/disable toggle). In passive state, connection cannot be used but its configuration is saved.
Advanced Features
Server-specific headers or protocol parameters can be added with additionalProperties.
Verification is performed before actual sending with addressToTest field and Test Mail button.
Saving the connection deploys it to the gateway and worker processes.
Ability to verify connection parameters before saving with "Test Connection" button.
Exporting Connection configuration as ZIP file. Importing to different environments (Development, Test, Production). Version control and backup capability.
Monitoring connection health and performance metrics.
Connection Parameters
Required Parameters
Description: Connection name (must be unique)
Example Value: Production_EmailSMTP
Notes: Should not start with space, special characters should not be used
Description: FQDN/IP information of SMTP server
Example Value: smtp.mailprovider.com
Notes: 255 character limit
Description: SMTP port number
Example Value: 587
Notes: 587 recommended for TLS, 465 for SSL
Description: Sender address to be used in messages
Example Value: noreply@company.com
Notes: Must be valid email format
Description: Body/header character set
Example Value: UTF-8
Notes: Comes as UTF-8 by default in UI
Description: SMTP account username
Example Value: alert.bot
Notes: Required when Auth toggle is on
Description: SMTP account password
Example Value: ••••••
Notes: Required when Auth toggle is on
Optional Parameters
Description: Description field for Connection purpose
Default Value: Empty
Recommended Value: Example: Prod alarm mail channel
Description: Toggle for upgrading to TLS
Default Value: false
Recommended Value: true in environments where TLS is mandatory
Description: Authentication requirement
Default Value: false
Recommended Value: true in most providers
Description: Address where test mail will be sent
Default Value: Empty
Recommended Value: Dev team distribution list
Description: Provider-specific key/value set for SMTP
Default Value: Empty array
Recommended Value: Like mail.smtp.connectiontimeout=15000
Description: Determines whether SSL/TLS is used for SMTP connection Default Value: false Recommended Value: true in production environments
Description: When enabled, the host name in the SMTP server certificate is verified Default Value: false
Description: Certificate selection used when SSL is active Default Value: Empty (system certificates are used) Recommended Value: Relevant certificate should be selected for self-signed servers
Usage Scenarios
Situation: Monitoring system produces critical alarm
Solution: Host=smtp.ops.local, From=alerts@company.com, Auth=true
Expected Behavior: Alarm mail goes to recipient list via TLS
Situation: OTP sent during authentication process
Solution: Port=587, Enable STARTTLS=true
Expected Behavior: OTP message is transmitted within seconds
Situation: Monthly reports with PDF attachments sent
Solution: AdditionalProperties with mail.smtp.writetimeout=120000
Expected Behavior: Large attachments sent without timeout
Situation: Dummy address for test environment scenarios
Solution: Environment=Test, Auth=false, From=test@dummy.local
Expected Behavior: Messages fall to sandbox SMTP
Situation: Secondary activates when primary SMTP is down
Solution: Host=primary, AdditionalProperties.failover=smtp2
Expected Behavior: Second host is used without flow interruption
Connection Configuration
Creating New Email Connection
Configuration Steps
- Click Connection option from left menu on Apinizer main screen.
- Select Email option from opened submenu.
- Email Connection list page opens.
- Click [+ Create] button in top right corner of page.
- New Email Connection creation form opens.
Enable Status (Active Status) Setting:
- Find Enable Status toggle at top of form.
- Set toggle to Active position (comes active by default).
- If you want to make Connection passive, set toggle to Passive position.
- Passive connections cannot be used in Integration Flows but their configurations are saved.
Name (Name) - Required Field:
- Enter a unique connection name in Name field.
- Name examples:
Production_EmailSMTP,Test_EmailConnection,Dev_SMTP_Alerts - Name rules:
- Should not start with space
- Special characters should not be used (recommended: letter, number, underscore)
- Maximum 255 characters
- System automatically checks as you type name:
- Green checkmark: Name is available
- Red X mark: Name already exists, select different name
Description (Description) - Optional:
- Enter text describing the purpose of connection in Description field.
- Example descriptions:
- "SMTP channel for alarms"
- "Production environment email notifications"
- "Dummy SMTP connection for test environment"
- Maximum 1000 character limit exists.
- This field can be left empty.
In the action button area at the top of the page, you can use the [<> Variable] button to select dynamic values, and with global variables, you can manage connection parameters with variable-based values instead of fixed values. For detailed information, review the Dynamic Variables page.
- Find Environment dropdown menu.
- Open dropdown menu and select one of the following options:
- Development: For development environment
- Test: For test environment
- Production: For production environment
- Different connection parameters can be defined for each environment.
- Environment selection determines in which environment connection will be active.
- Connections with same name can be created separately for different environments.
Host (Server Address) - Required:
- Enter SMTP server address in Host field.
- Host format:
- FQDN (Fully Qualified Domain Name):
smtp.mailprovider.com - IP address:
192.168.1.100 - Maximum 255 character limit exists.
- Get correct host address from your SMTP provider's documentation.
Port (Port Number) - Required:
- Enter SMTP port number in Port field.
- Common port numbers:
- 25: Standard SMTP (usually unencrypted)
- 465: SMTP with SSL/TLS (SMTPS)
- 587: SMTP with STARTTLS (recommended)
- Check correct port number from your SMTP provider's documentation.
- Port number must be between 1-65535.
Enable STARTTLS Setting:
- Find Enable STARTTLS toggle.
- If your SMTP provider requires TLS/STARTTLS, set toggle to Active position.
- If using port 587, STARTTLS should generally be active.
- If using port 465, STARTTLS is generally not needed (SSL/TLS is used directly).
- Check provider documentation to make correct setting.
Port 587 and STARTTLS combination is recommended for most modern SMTP providers.
Use SSL Setting:
- Find Use SSL toggle.
- If your SMTP server requires SSL/TLS, set toggle to Active position.
- When SSL is enabled, a certificate can optionally be selected.
- If no certificate is selected, default JVM certificates are used.
- For SMTP servers using self-signed certificates, you can define the relevant certificate in Secrets Management → Certificates and select it here.
From (Sender Address) - Required:
- Enter sender email address in From field.
- Format: Must be valid email address format.
- Examples:
noreply@company.com,alerts@company.com,test@dummy.local - This address will appear as sender in all sent emails.
- Ensure your DNS/SPF records support this address.
Auth (Authentication) Setting:
- Find Auth toggle.
- If your SMTP server requires authentication, set toggle to Active position.
- Most modern SMTP providers require authentication.
Username (Username) - Required when Auth is on:
- If Auth toggle is active, Username field becomes visible.
- Enter username of your SMTP account.
- Examples:
alert.bot,smtp.user,noreply@company.com - In some providers, username may be full email address.
- Check correct format from your SMTP provider's documentation.
Password (Password) - Required when Auth is on:
- If Auth toggle is active, Password field becomes visible.
- Enter password of your SMTP account.
- Password will appear masked for security reasons.
- You can click eye icon to see password.
- Use of secret manager is recommended for sensitive information.
This connector has no dedicated timeout or connection pool field; SMTP-side timeouts can be provided through the Additional Properties section using mail.smtp.* keys (detailed in Step 7).
Additional Properties (Additional Properties) - Optional:
- Find Additional Properties section.
- Use this section to add provider-specific parameters for your SMTP provider.
- Add parameters in Key-Value format:
- Example:
mail.smtp.connectiontimeout=15000 - Example:
mail.smtp.writetimeout=120000 - Commonly used properties:
mail.smtp.connectiontimeout: Connection timeout (milliseconds)mail.smtp.timeout: General timeout (milliseconds)mail.smtp.writetimeout: Write timeout (milliseconds)mail.smtp.auth.mechanisms: Authentication mechanism- Add one key-value pair per line.
- Check supported properties from your SMTP provider's documentation.
AddressToTest (Test Address) - Optional:
- Find AddressToTest field.
- Enter email address to be used for test mail sending.
- This address is where test mail will be sent when Test Connection button is clicked.
- Example:
dev-team@company.com,test@dummy.local - This field can be left empty, but filling it is recommended for testing.
- Find [Test Connection] button at bottom of form or in top right corner.
- Click button.
- System tests connection parameters:
- Connection is established to SMTP server
- Authentication is performed (if Auth is active)
- STARTTLS handshake is performed (if active)
- Test mail is sent (if AddressToTest is filled)
- Test result:
- Successful: Green confirmation message is displayed, message like "Connection test successful"
- Failed: Red error message is displayed, error details are shown
- In error case:
- Read error message
- Check relevant parameters (Host, Port, Username, Password)
- Check firewall and network settings
- Check SMTP provider documentation
- Fix parameters and test again until test is successful.
- Ensure all required fields are filled.
- Verify that test connection is successful (recommended).
- Click [Save and Deploy] button in top right corner of form.
- System saves connection and deploys to selected environment.
- After successful save:
- You are redirected to Connection list page
- New connection appears in list
- Connection becomes Enabled status
- Becomes available for use in Integration Flow and Connector steps
Checklist (Before Saving):
- Name field is unique and valid
- Host and Port fields are filled
- From address is in valid email format
- If Auth is active, Username and Password are filled
- Environment is selected
- Test Connection is successful (recommended)
- All required fields are filled
Result:
- Connection is successfully created and saved
- Becomes active in selected environment
- Connection selection can be made in Integration Flow and Connector steps
- Is displayed and can be managed in Connection list
Connection created successfully! You can now use it in Integration Flow and Connector steps.
Deleting Connection
Select Delete from ⋮ menu at end of row or click [Delete] button on connection detail page
Check Before Deleting: May be used in Integration Flow or Connector steps. Assign alternative connection if necessary. Backup with Export before deleting
Alternative: Deactivate
- Use Disable option instead of deleting.
- Connection becomes passive but is not deleted.
- Can be reactivated when needed.
Exporting/Importing Connection
In this step, users can export (export) existing connections for backup, moving to different environments, or sharing purposes, or import (import) a previously exported connection again. This operation is used to maintain data integrity in version control, transitions between test and production environments, or inter-team sharing processes.
Export
Click [Export] button on Connection detail page. ZIP file is downloaded.
The row's ⋮ menu now has two items: the primary Export opens the Export/Import Wizard with this connection preselected — its certificate/key store and any ${VARIABLE} reference surface automatically on the dependency step; the secondary Export as File downloads the ZIP described below directly, without going through the wizard.
Format: Date-connection-ConnectionName-export.zip
Example: 13 Nov 2025-connection-Production_EmailSMTP-export.zip
- Connection JSON file
- Metadata information
- Dependency information (e.g., certificates, key store)
- Backup
- Moving between environments (Test → Prod)
- Versioning
- Team or project-based sharing
Import
- Click [Import Email] button on the main list — it now opens the Export/Import Wizard's import step with type Connection preselected (Admin scope when opened from Administration); the old upload dialog is gone.
- Select the exported package and follow the wizard's steps.
- The wizard checks format, name conflicts and dependency availability before you confirm the import.
Scenario 1: Name Conflict → Overwrite old connection or create with new name.
Scenario 2: Missing Dependencies → Create missing certificates or key stores first or exclude during import.
Usage Areas of Connection
Steps:
- Create Connection.
- Verify connection with Test Connection.
- Save and activate with Save and Deploy.
- Ensure Connection is in Enabled status
Connection is selected in steps requiring email sending. Examples: steps like "Send Email", "Email Notification", "Email Alert". Connection selection is made from Connection field in these steps' configuration
Connection is selected in scheduled tasks (e.g., sending messages at certain intervals, file processing, etc.) to access external systems. When Connection changes, job execution behavior is also updated accordingly
Connection accuracy can be checked independently of Integration Flow with Connection Test feature. This test is critical in debugging process
Best Practices
Things to Do and Best Practices
Bad: Managing different providers with same Connection.
Good: Opening separate Connection for each provider.
Best: Specifying environment + provider combination in name (Prod_SendGrid)
Bad: Changing from field with random addresses.
Good: Using meaningful addresses according to business processes.
Best: Defining corporate alias compatible with DMARC/SPF records
Bad: Never updating shared passwords.
Good: Rotating manually at intervals.
Best: Setting up rotation automation through secret manager
Bad: Leaving additionalProperties field empty.
Good: Adding only needed keys.
Best: Recording all mandatory SMTP properties from provider documentation
Bad: Using same connection parameters in all environments.
Good: Creating separate connection for each environment.
Best: Using a single connection in all environments by defining the values that change per environment (host, user, password, etc.) with environment variables
Bad: Saving and deploying Connection without testing.
Good: Verifying with Test Connection before saving.
Best: Testing after each parameter change, performing full integration test in test environment before moving to production
Security Best Practices
When Auth is on, username/password should only be visible to necessary roles. Do not copy and share passwords through UI
Limit enable/disable permissions to teams responsible for email infrastructure; incorrect configuration can stop all notifications
If sensitive keys exist in additionalProperties, keep values with masked secret references
Store sensitive information such as username and password using environment variable or secret manager. Do not hardcode credentials in code or configuration files. Update passwords periodically
Always enable SSL/TLS in Production environment. Use self-signed certificates only in development environment. Track certificate expiration dates and renew on time
Allow only authorized users to change Connection configuration. Store Connection change logs. Apply change approval process for critical connections
Things to Avoid
Why to avoid: All email flow stops when primary SMTP service is interrupted.
Alternative: Define secondary host with additionalProperties or separate Connection
Why to avoid: Password leak affects all processes.
Alternative: Open separate user account for each application, audit accesses
Why to avoid: SPF/DKIM incompatibility causes emails to fall into spam folder.
Alternative: Use approved domain aliases and keep DNS records up to date
Why to avoid: Test data may be written to production system, real users may be affected, security risk occurs.
Alternative: Create separate connection for each environment, use environment variables for values that change per environment, separate connection names by adding prefix according to environment (Test_, Prod_)
Why to avoid: Connection constantly times out in network delays, Integration steps fail.
Alternative: Adjust timeout values according to real usage scenarios, measure network latency and determine timeouts accordingly
Performance Tips
Recommendation: Prefer SMTP hosts in same datacenter.
Effect: Network delay decreases, timeout risk decreases
Recommendation: Adjust mail.smtp.connectiontimeout, mail.smtp.writetimeout values according to real load tests.
Effect: Stable performance even with large attachments
Recommendation: Trigger Test Connection API in CI/CD.
Effect: Incorrect configurations are caught before moving to production
Recommendation: Measure real network latency, adjust timeout values accordingly, avoid very low or very high timeouts.
Effect: Unnecessary waits are prevented, fast fail-over is provided, user experience improves
Recommendation: Track timeout rates, perform connection health check, set up alerting.
Effect: Problems are detected proactively, performance bottlenecks are identified early, downtime decreases
Troubleshooting
Email Not Delivered
Wrong from domain, SMTP provider blocked, or TLS may be mandatory but disabled.
Verify DNS/SPF records.
Check provider logs.
Open Enable STARTTLS toggle and test again.
Test Mail Failed
addressToTest may be invalid, Auth information may be wrong, or SMTP port may be closed in firewall.
Update test address.
Re-enter credentials.
Verify port opening from network team.
Connection Timeout
Network delay, target system responding slowly, or timeout value may be too low.
Check network connectivity.
Check target system health.
Increase timeout values.
Review Connection logs.
Authentication Failed
Wrong username/password, expired credentials, or permission problem may exist.
Verify credentials.
Check that user is active in target system.
Check that necessary permissions are granted.
Check SSL/TLS certificates.
Connection Test Successful But Integration Flow Gives Error
Different connection may be selected in Integration/Connector step, step may be incorrectly configured, or Flow/Job may not have been redeployed.
Check that Connection's enable toggle is active.
Verify that correct connection is selected in Integration Flow.
Redeploy Connection.
Redeploy Integration Flow or Job.
Check Gateway logs.
Frequently Asked Questions (FAQ)
Can I keep multiple sender addresses in Email Connection?
Single Connection can carry single from address; create separate Connection by cloning for different addresses or use application-level override.
Will there be a problem if I enable TLS in provider where STARTTLS is not mandatory?
Most SMTP servers support STARTTLS command, if not supported you will get error at handshake stage; in this case close toggle.
Which key/values can I add to Additional Properties field?
Provider's JavaMail compatible parameters (mail.smtp.connectiontimeout, mail.smtp.auth.mechanisms, etc.) are supported; key and value are free text.
Does mail go to real recipients with Test Connection?
No, only single mail is sent to address entered in addressToTest field; Integration Flow is not triggered.
Can I use this Connection in connector mode as well?
Yes, when connectorMode is activated from connector screen, same form is used and your saved Connection appears in list.
Can I use the same connection in multiple Integration Flows?
Yes, the same connection can be used in multiple Integration Flow or Connector steps. This provides central management and guarantees configuration consistency. However, care should be taken as changes made to connection will affect all usage locations.
Should I create different connections for Test and Production?
Yes, it is recommended that you create separate connection for each environment. Alternatively, you can use a single connection in all environments by defining the values that change per environment with environment variables. This approach provides easier management and less error risk.
Test Connection successful but not working in Integration Flow, why?
Several reasons may exist:
- Connection enable toggle may be passive
- Different connection may be selected in Integration step
- Connection may not have been deployed
- Integration Flow may not have been redeployed yet