FX Blue email library - User guide

The Email Library is a simple DLL which provides all the email functionality missing from MT4: multiple recipients, attached files, HTML formatting, support for GMail etc.

1Overview and installation

1.1Overview of the MT4 Email Library

The MT4 Email Library is a library for MT4 software developers which overcomes various weaknesses of MT4's own built-in email handling. The MT4 Email Library caters for the following:

  • HTML-formatted messages
  • Attached files
  • Multiple recipients
  • Altering the sender name
  • Using mail servers which require SSL (e.g. Gmail)
  • CC and BCC recipients

As with MT4's built-in email handling, all message transmission is asynchronous (to avoid blocking trade execution), and MQ4 script therefore cannot tell whether a message has been successfully delivered.

External code such as the MT4 Email Library cannot access MT4's email settings, and cannot write to MT4 log files. Therefore, MQ4 script which uses the library has to provide the full details of each message to send, including mail server details. Success or failure of messages is recorded in a separate log file, not in the MT4 journal.

1.2Installing the library

The installer which you download from the FX Blue website does a fully automated installation of the library (putting all the required files into MT4's MQL4\Libraries directory).

1.2.1.NET Framework

The MT4 Email Library requires version 3.5 of the .NET Framework. This should already be present on almost all Windows computers, but can be obtained if necessary from the following address:

http://www.microsoft.com/en-us/download/details.aspx?id=22

1.3Licence

Unless otherwise specified in writing by FX Blue, this software is licensed for personal use only. You are not allowed to distribute it to other people, regardless of whether or not money is changing hands. You only have a licence to use the software if you, personally, downloaded it from our website.

The software is provided entirely at the user's risk, and you should check it thoroughly before deploying it on computers trading real money. FX Blue accepts no responsibility whatsoever for any loss of any kind caused by installation or use of the software.

2Using the MT4 Email Library

N.B. Any MQ4 code which uses the MT4 Email Library needs to be able to call DLL files. The "Allow DLL imports" setting must be turned on, either in the properties for the individual EA/script or at global level in MT4's Tools/Options/Expert Advisors settings. Please note that the global setting does not affect any EAs which are already running; it is the default which is used when you next add an EA or script to a chart.

An example of using MT4 Email Library can be found in the file "Example MQL for MT4 Email Library.mq4".

2.1Importing MT4EmailBridge.dll

The first step in using the library from MQ4 code is to import the DLL using a declaration such as the following:

#import "MT4EmailBridge.dll"
  int SendEmailW(string SMTPServer, int SMTPPort, string SMTPUsername, string SMTPPassword, 
                 int RequiresSSL, string EmailFromAddress, string EmailFromName, string EmailToAddress, 
                 string EmailToName, string CCRecipient, string BCCRecipient, string Subject, 
                 string Body, int IsHtmlEmail, string AttachedFiles, int Flags);
#import

2.2Calling the SendEmailW() function

The library provides one single function: SendEmailW(). The parameters for this function are as follows:

Parameter

Description

SMTPServer

The name or IP address of the mail server to use. For example, "smtp.gmail.com"

SMTPPort

The port to use on the mail server. Normally 25 for servers which do not require authentication, or 587 for things like Gmail and Yahoo

SMTPUsername

Any username required by the mail server. Can be left blank.

SMTPPassword

Any password required by the mail server. Can be left blank.

RequiresSSL

1 if the mail server requires SSL (encryption), or 0 if not. For example, Gmail does require SSL whereas Yahoo does not (on port 587).

EmailFromAddress

The from-address for the email. For services such as Gmail, the address used here must have been verified within Gmail.

EmailFromName

The sender name to display. Can be left blank.

EmailToAddress

One or more recipient email addresses. Multiple addresses should be separated with commas or semi-colons - e.g. "billg@microsoft.com,steveb@microsoft.com"

EmailToName

One or more recipient names. Can be left blank, but including names makes messages slightly less likely to be classed as spam. Multiple names should be separated with commas or semi-colons - e.g. "Bill Gates;Steve Ballmer"

CCRecipient

One or more email addresses for CC recipients. Multiple addresses should be separated with commas or semi-colons. Please note that you can only supply addresses for CC recipients, not names.

BCCRecipient

One or more email addresses for BCC recipients. Multiple addresses should be separated with commas or semi-colons. Please note that you can only supply addresses for BCC recipients, not names.

Subject

The subject for the email

Body

The body text for the email. Can be either plain-text, or HTML such as:

<html><body>This is a <b>test</b></body></html>

IsHtmlEmail

1 if the Body is HTML-formatted, or 0 if plain text

AttachedFiles

One or more files to attach to the email. Multiple files should be separated by commas or semi-colons. The filenames should be fully specified from root, e.g.:
"c:\temp\file1.txt,c:\temp\file2.txt"

Flags

Controls whether messages are logged, in the Windows event logs. A value of 0 logs both successful and failed messages. A value of 1 only logs failed messages.

The SendEmailW() function should return more or less immediately. As with MT4's own built-in SendMail() function, message transmission is asynchronous and MQL4 code cannot tell whether a message has been successfully delivered.

2.3Message logging and return values from the SendEmailW() function

Message transmission from the library is asynchronous. Success or failure of messages is recorded in a separate log file, not in the MT4 journal. You can turn off logging of successful messages using the Flags parameter for SendEmailW().

The return value from SendEmailW() indicates whether the message was successfully queued for delivery. Because transmission is asynchronous, it does not indicate whether the message has successfully reached its recipient(s).

Possible values are as follows:

Return value

Meaning

100

Message transmission has begun successfully. Success/failure should be recorded in the log file.

-1

Unable to create a temporary file on disk (in the Windows temporary directory). This will usually indicate a severe lack of free disk space.

-2

Unable to start the applet which sends the email. Implies either an installation problem (such as a missing installation of the .NET Framework) or severely low resources on the computer

2.3.1Log file

All messages which are successfully queued for delivery (i.e. return value of 100 from SendEmailW) are logged in daily files in the following directory:

C:\Users\<your username>\AppData\Local\MT4-Email

Personal Trade Copier

Trade Mirror

Trading Simulator

Figaro App Suite

Publisher EA

Figaro Connector EA

All Trader Downloads

All Developer Downloads

Currency Strength

Trader Sentiment

Price Alerts

Mini Charts

Premium Charting

Market Scanner

All Tools

Next High Impact Events

Week View

Next 24 Hours

Session Map

Chart View

Future Events

Past Events

Big Market Movers

Compare Brokers

Broker Offers

Market Analysis

Price Action News

Broker News

Example Analysis

Widgets

FAQ

Statement

Stats

Risk analysis

Widgets

Portfolio

FAQ

Please Log In
Not yet a user?