SMTP Integration
OMICard Operation Manual
1. Summary
1.1 SMTP Use Case
Sending newsletters can be as simple as sending mail through Outlook.
By sending through ITPison SMTP, enterprise IT and developers can completely eliminate the cost of managing a mail server — outbound mail only needs to be routed through the ITPison mail relay.
1.2 Configuration Steps
a. First configure OMICard and enable the option.
b. Configure SMTP.
1.3 SMTP Configuration Parameters
SMTP Server: smtp.itpison.com
Port: 465
SSL encryption
Account authentication required; enter the OMICard sign-in account and password.
2. OMICard Configuration
2.1 Sign in to OMICard
Go to the "ITPison" official website and click "Member Login":
2.2 Enable NewerMail
Sign in with your OMICard registered account. As shown below, click "Messages" → "SMTP Settings" in the upper right.
Select "Enable" and then save the settings.
3. SMTP Configuration Parameters
3.1 Ports and Encryption Levels
A port is a communication channel between two computer systems; encryption indicates whether data is encrypted during the communication. In mail transmission, the ports internationally reserved for SMTP are commonly 25, 587, and 465. The encryption used during transmission is either SSL or TLS (STARTTLS).
The transport encryption protocol TLS is in fact a newer version of SSL; from SSL 3.0 onward, the version was renamed TLS 1.0. However, the TLS referred to in SMTP transmission is "STARTTLS". The difference between SSL and STARTTLS is that with SSL, data encryption begins as soon as the two communicating parties establish the connection. With STARTTLS, encryption is only performed after the connection has been established and one side specifically requests that encryption begin. Architecturally, SSL provides better protection of data transmission than STARTTLS.
Any port can be paired with a different encryption method. Although there are internationally common ports and corresponding encryption methods, the SMTP server can explicitly list the ports and encryption it uses, and the client only needs to configure according to the description provided by the SMTP server.
Internationally common SMTP ports
- 25: The earliest and most standard port of the SMTP protocol. Normally used unencrypted, but can also be configured for encryption if both communicating parties agree.
- 465: Commonly used as the SSL port. Most current mail systems use this port together with encryption.
- 587: Commonly provided for TLS (STARTTLS) use.
In addition to the common communication ports above, ITPison can provide a specific port for use upon customer request.
3.2 Port 25, no encryption
SMTP server: smtp.itpison.com
(backup: smtp2.itpison.com)
Account: OMICard sign-in account
Password: OMICard sign-in password
Port: 25
Encryption level: none
3.3 Port 465, SSL encryption
SMTP server: smtp.itpison.com
(backup: smtp2.itpison.com)
Account: OMICard sign-in account
Password: OMICard sign-in password
Port: 465
Encryption level: SSL
3.4 TLS (STARTTLS)
SMTP server: smtp.itpison.com
(backup: smtp2.itpison.com)
Account: OMICard sign-in account
Password: OMICard sign-in password
Port: 25, 587
Encryption level: TLS (STARTTLS)
SMTP error: Failed to connect to SMTP host. Connection failed. stream socket enable crvptoo: Peer certificate CN='*.ipison.com' did not match expected CN='smtp.itpison.com'
4. SMTP Testing
4.1 Web-based SMTP Testing
After configuration, you can use any of the following web-based SMTP tools to test:
4.2 Web-based SMTP Demonstration Test
4.2.1 Gmass.com Test
The following uses https://www.gmass.co/smtp-test as a demonstration.
Enter the required parameters first:
SMTP Server: smtp.itpison.com
Port: 25 or 465 (encrypted)
Full SMTP transmission process
After the test starts, the full SMTP transmission process can be seen on the page.
4.2.2 Smtper.net Test
If a test produces an error message, you can use a different testing site to rule out an issue with the testing site itself.
The following uses https://www.smtper.net/ as a demonstration.
4.2.3 Receiving the Test Email
The test email should then appear in the inbox, indicating that all SMTP settings are correct. If the test email is not received, the test has failed; the transmission error messages above can be provided to ITPison for investigation.
The email body contains only a single line "Test message", but the sender shown is the value entered in the SMTP test page.
(▲ SMTP test email received successfully)
5. Sample Code
5.1 Python Code Sample
import smtplib
from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText
# SMTP server configuration
smtp_server = "smtp.itpison.com"
smtp_port = 465
smtp_username = "sign-in name"
smtp_password = "sign-in password"
# Email content
from_email = "sender email address"
from_name = "sender name"
to_email = "recipient email address"
to_name = "recipient name"
reply_to_email = "reply-to email address" # Added Reply-To address
subject = "Test Mail"
html_body = """
<p>This is a test mail!!</p><br>
"""
# Create message container
msg = MIMEMultipart("alternative")
msg["From"] = f"{from_name} <{from_email}>"
msg["To"] = f"{to_name} <{to_email}>"
msg["Subject"] = subject
msg["Reply-To"] = reply_to_email # Set Reply-To header
# Attach the HTML body
msg.attach(MIMEText(html_body, "html"))
try:
# Connect to the SMTP server
server = smtplib.SMTP_SSL(smtp_server, smtp_port)
server.login(smtp_username, smtp_password)
# Send email
server.sendmail(from_email, to_email, msg.as_string())
server.quit()
print("Message has been sent")
except Exception as e:
print(f"Message could not be sent. Error: {str(e)}")
6. Common Troubleshooting
6.1 Incorrect SMTP Configuration
Most SMTP test failures result from incorrect settings. Please verify:
a. The NewerMail option in the OMICard back-end is set to "Enable".
b. The SMTP parameters are configured exactly as described in this manual.
6.2 Outbound SMTP Blocked by Local Network
If you are using a residential dynamic IP (fiber, ADSL), 4G/5G mobile broadband, or shared virtual hosting (for example a WordPress hosted site), these network service providers may block outbound SMTP and prevent port 25 from connecting outbound.
If the web-based SMTP test can receive mail successfully, but your own outbound network cannot connect to smtp.itpison.com on port 25, this means your network has blocked outbound SMTP port 25. A static IP line is usually required to use outbound SMTP connections on port 25.
7. [Advanced] SMTP Connection Send Parameter Settings
Note: This section covers advanced options that use mail headers to issue mail-sending instructions.
7.1 X-Header
Over an SMTP connection (25/465/587 SSL/TLS), the user's default options can be configured in EmailUserLaunchSettingInfo, or X-Header control options can be added to the mail header. The following options can be combined and used at the same time:
- JobName: Job name. Header name: X-JobName
- RefNumber: Job reference number. Header name: X-RefNumber
- NextLaunchTime: Scheduled launch time. Header name: X-NextLaunchTime
- LaunchExpireTime: Launch expiration time. Header name: X-LaunchExpireTime
- LaunchType: Header name: X-LaunchType
- LaunchClass: Header name: X-LaunchClass
- LaunchOption: Header name: X-LaunchOption
- JobOption: Header name: X-JobOption
- ListOption: Header name: X-ListOption
- LinkOption: Header name: X-LinkOption
- SendOption: Header name: X-SendOption
Note: For the option values of LaunchOption / JobOption etc., refer to Appendix A: EmailOption.
7.2 X-Header Examples
7.2.1 Do not track opens
X-LinkOption: 64
From: test@itpison.com
To: test@gmail.com
Subject: Test Sample
This is Test Email
Python sample:
import smtplib
from email.mime.text import MIMEText
# SMTP server configuration
smtp_server = "smtp.itpison.com"
smtp_port = 465
smtp_username = "sign-in name"
smtp_password = "sign-in password"
# Email content
from_email = "test@itpison.com"
to_email = "test@gmail.com"
subject = "Test Sample"
custom_header_key = "X-LinkOption"
custom_header_value = "64"
body = "This is Test Email"
# Create email message
msg = MIMEText(body, "plain")
msg["From"] = from_email
msg["To"] = to_email
msg["Subject"] = subject
msg.add_header(custom_header_key, custom_header_value) # Add custom header
try:
# Connect to the SMTP server
server = smtplib.SMTP_SSL(smtp_server, smtp_port)
server.login(smtp_username, smtp_password)
# Send email
server.sendmail(from_email, to_email, msg.as_string())
server.quit()
print("Message has been sent")
except Exception as e:
print(f"Message could not be sent. Error: {str(e)}")
7.2.2 Do not track links
X-LinkOption: 128
From: test@itpison.com
To: test@gmail.com
Subject: Test Sample
This is Test Email
7.2.1 Do not track opens and links
X-LinkOption: 192
From: test@itpison.com
To: test@gmail.com
Subject: Test Sample
This is Test Email
7.2.1 Do not track opens and links
X-LinkOption: 192
From: test@itpison.com
To: test@gmail.com
Subject: Test Sample
This is Test Email
7.2.1 Keep all To headers
X-ListOption: 1
From: test@itpison.com
To: test@gmail.com
Subject: Test Sample
This is Test Email
7.2.1 Keep all Cc headers
X-ListOption: 2
From: test@itpison.com
To: test@gmail.com
Subject: Test Sample
This is Test Email
7.2.1 Do not filter list
X-ListOption: 65536
From: test@itpison.com
To: test@gmail.com
Subject: Test Sample
This is Test Email
8. Appendix A: EmailOptions
1. LaunchOption
-
const int cLHRemoveFilesAfterCompleteOption=1; -
const int cLHRemoveDataAfterCompleteOption=2; -
const int cLHPendApproveOption=4;// pended launch after approved const int cLHAutoGenRefNumberOption=8;const int cLHProcessSubListOption=16;-
const int cLHNotCreateJobFolderOption=32;// launcher will use launch folder as job folder -
const int cLHNotCreateLaunchFolderOption=64;// requester save everyhing, string, filepath, in db -
const int cLHCreateJobOption=128;// requester creat job if possible -
const int cLHMLContentSampleListOption=256;// multi-launch content -
const int cLHCheckExtTimeOption=512;// Check StartTime, ExpireTime From LaunchExtTimeInfo -
const int cLHCheckListOption=1024;// Check List Count From LaunchCheckListInfo
2. JobOptions
const unsigned int cJBDoResendMask=1;-
const unsigned int cJBActiveContentMask=2;// for asp or aspx dynamic merge content const unsigned int cJBCreateReportMask=4;-
const unsigned int cJBConvertHtmlToTextFormat=8; -
const unsigned int cJBDynaMergeMask=16;// use dyna merge -
const unsigned int cJBMergeDelMask=32;// user defined merge del -
const unsigned int cJBProcessOptionMask=64;// user defined Process option -
const unsigned int cJBBackupSendMessage=128;// backup a copy of EML -
const unsigned int cJBAuditSendMessage=256;// audit send EML -
const unsigned int cJBConvertContentToUTF8Mask=512; -
const unsigned int cJBAddContentLocationToHtml=1024; -
const unsigned int cJBGetSubjectFromHTMLTitleMask=2048; -
const unsigned int cJBAutoAdjustCharSetToContentCharSet=8192;// auto adjust charset according to email content otherwise adjust content accoring to job charset -
const unsigned int cJBAutoAdjustHeaderCharSetToContentCharSet=16384;// auto adjust subject, fromdisplay,replydisplay, todisplay charset as same as content -
const unsigned int cJBLandSameWebFolderOnly=32768;// if tracklayer > 0, only get the page from the same web folder -
const unsigned int cJBAutoGetLandPageMask = 131072; -
const unsigned int cJBConverTextToHTMLMask = 262144; -
const unsigned int cJBAddExternRefToEmailMask = 1048576; -
const unsigned int cJBSaveWebPageAsMht=2097152; -
const unsigned int cJBHtmlExtElementMask=134217728; -
const unsigned int cJBAddOutlookDeliveryReceiptMask =268435456; -
const unsigned int cJBAddOutlookReadReceiptMask =536870912; -
const unsigned int cJBRemoveFilesAfterComplete=2147483648;
3. LinkOption
-
const unsigned int cLKConvertExtLinkToIntResource=1;// 0: convert cid, content-location images to link 1: convert link to cid -
const unsigned int cLKAddQStrToLinkMask=2;// append GA parameters to external links -
const unsigned int cLKKeepDuplicateLinkMask=4; -
const unsigned int cLKAutoCleanLink=8;// remove amp; from link const unsigned int cLKAddBaseToUrl=16;-
const unsigned int cLKAutoGetLinkNameFromTextMask=32; const unsigned int cLKNotTrackOpenMask=64;-
const unsigned int cLKNotTrackAllLinkMask=128; -
const unsigned int cLKTrackNameLinkOnlyMask=256; -
const unsigned int cLKNotTrackMailToLinkMask=512; -
const unsigned int cLKTrackFrameLinkMask=1024; const unsigned int cLKNotTrackMMSMask=2048;-
const unsigned int cLKNotConvertMMSMask=4096; -
const unsigned int cLKNotConvertImageAsOpenLinkMask =8192; -
const unsigned int cLKTrackQRCodeLinkMask=16384;
4. ListOption
-
const unsigned int cLTKeepToHeader=1;// keep job's to const unsigned int cLTKeepCcHeader=2;-
const unsigned int cLTAutoAdjustInvalidList=8; const unsigned int cLTNoLineEsc=16;const unsigned int cLTRemoveUnsubMask=32;const unsigned int cLTRemoveDupMask=64;const unsigned int cLTRemoveBlackMask=128;const unsigned int cLTRemoveWhiteMask=256;const unsigned int cLTRemoveReturnMask=512;const unsigned int cLTSampleListOnly=1024;const unsigned int cLTSampleAndSendAll=2048;-
const unsigned int cLTCheckListFileTypeFromListContent=4096; -
const unsigned int cLTNotExpandToAddress=8192;// not add list column to to list -
const unsigned int cLTNotExpandCcAddress=16384;// not add list column cc to list -
const unsigned int cLTNotExpandBccAddress=32768;// not add list column bcc to list -
const unsigned int cLTBypassAllListProcessFilter=65536;// Bypass all list filtering and processing and Add List to NewListPool -
const unsigned int cLTRemoveDeliverMask = 131072; -
const unsigned int cLTRemoveResponseMask = 262144; -
const unsigned int cLTNotToRemoveSystemBlackMask=524288; -
const unsigned int cLTNotToRemoveSystemRemoveWhiteMask=1048576;
5. SendOption
const unsigned int cSDSendListMask=15;-
const unsigned int cSDSendMainListOnly=0;// email onnly -
const unsigned int cSDSendMainListFirst=1;// email first > sms -
const unsigned int cSDSendSubListFirst=2;// sms first > email -
const unsigned int cSDSendSubListOnly=3;// sms only -
const unsigned int cSDSendBothList=4;// bth email and sms
6. FormerOption
a. Content
const int cFormerCTHtmlMask=1;const int cFormerCTTextMask=2;const int cFormerCTAttachmentMask=4;const int cFormerCTMergeMask=8;const int cFormerCTSubjectMask=16;const int cFormerCTFromDisplayMask=32;const int cFormerCTReplyDisplayMask=64;const int cFormerCTToDisplayMask=128;
b. List
-
const int cFormerLTUnknownMask=1;// not open const int cFormerLTOpenMask=2;const int cFormerLTOpenNotClickMask=4;const int cFormerLTClickMask=8;const int cFormerLTForwardMask=16;const int cFormerLTForwardOutMask=32;const int cFormerLTReturnMask=64;const int cFormerLTReplyMask=128;const int cFormerLTUnsubscribeMask=256;const int cFormerLTSubscribeMask=512;const int cFormerLTContactMask=1024;const int cFormerLTSendErrorMask=2048;const int cFormerLTClickNotOpenMask=4096;
7. AttachOption
a. bit position
- 1st bit: 0: no convert to link, 1 convert to link
- 2nd bit: (only when 1st bit is 0) 0: no authenticate, 1 Authenticate Page
- 3rd bit: (only when 1st bit is 1) 0: not track link, 1 track link
- 4th bit: (only when 2nd bit is 1) 0: system show authenticate accept page 1: third Party show authenticate accept Page (when AuthenticateURl is presented)
- 5th bit: (only when 2nd bit is 1 and only if 3rd bit is 0) 0: form post back to system (if AuthenticateURl is presented then 3rd part authenticate, otherwise system suthenticate), 1 form post directly to third Party authenticate Page (when AuthenticateURl is presented)
- //6th bit: 0 form post, 1 form get
- 6th bit: (only when 1st bit is 1) 0: one attchamen link one line 1: align all attachment links in one line
- 7th bit: 1 convert attachment to PDF
- 8th bit: 0: checksource is referer 1: checksource is ip
- 9th bit: 1 Support Dynamic Merge, such asp, aspx
- 10th bit: 1 compress attachment
- 11th bit: 1 uncompress attachment
- 12th bit: 1 check/determine attachment as email list by comparing system/user defined name (AttAsListFileName), usually check attachments from eml file
- 13th bit: 1 support Dynamic function Merge
- 14th bit: 1: track open
- 15th bit: 1: track click
b. const
const int cAttachConvertLinkMask=1;const int cAttachAuthenticateMask=2;const int cAttachTrackLinkMask=4;const int cAtachShowThirdPartyMask=8;const int cAttachPostThirdPartyMask=16;//const int cAttachGetMask=32;const int cAttachAlignLinkMask=32;const int cAttachConvertPDFMask=64;const int cAttachCheckSourceIPMask=128;const int cAttachSupportActiveMergeMask=256;const int cAttachCompressMask=512;const int cAttachUnCompressMask=1024;const int cAttachAsListFileMask=2048;const int cAttachSupportDynaMergeMask=4096;const int cAttachTrackOpenMask=8192;const int cAttachTrackClickMask=16384;
8. Link Position
enum eAddPosition {
eTopLeft=0,
eTopMiddle=1,
eTopRight=2,
eBottomLeft=3,
eBottomMiddle=4,
eBottomRight=5,
eMergeLink=9
};
9. LinkType
const int cLinkMask=255;const int cMergeLinkMask=256;const int cFrameLinkMask=512;const int cLandLinkMask=1024;const int cHTMLLinkMask=2048;const int cTextLinkMask=4096;const int cOpenLinkMask=8192;const int cQrcodeLinkMask=16384;const int cAddEmailMask=32768;const int cAddRefMask=65536;const int cAddQStrMask=131072;const int cNoUrlEncode=262144;const int cReadReciptMask=524288;
10. LinkClass
enum ELinkClassType {
eRegularLink=0,
eOMISLink=1,
eApproveLink=2,
eForwardLink=3,
eUnsubscribeLink=4,
eSubscribeLink=5,
eContactLink=6,
eAuthenticateLink=7,
eRegisterLink=8,
eOrderLink=9,
eUpdateLink=10,
eQuestionaryLink=11,
eActivateLink=12,
eFromActivateLink=13,
eAgreeLink=14,
eConfirmLink=15,
eStateLink=16,
eReceiptLink=17,
eEmailBodyLink=100,
eAttachmentLink=128,
eAttachReceipt=129,
eAttachReceipt2=130
};
JobType=2 => DeliverType
enum EDeliveryType {
eEmail=0,
eNews=1,
eFax=100,
ePaper=200
};
JobType=1 => DeliverType
enum eDeliveryType {
eSMS=0, // SMS
eMMS=1, // MMS
// for IM Message
eIM_MSN=11,
eIM_Skype=12,
eIM_Yahoo=13,
// for mobile app
eAppPush=100,
eLinePush=200,
eWeChatPush=300,
eIGPush=400
};