GDI Print Directives > Email > SMTP Authentication

This topic last updated 11 December 2023

Most SMTP servers these days require some form of authentication—of which there are many forms available—in an effort to reduce spam. A-Shell will negotiate with the SMTP server and use the most secure form that both server and client support. If this doesn't succeed, A-Shell will pop up a debug message window, displaying all of the details of the negotiation, allowing it to be readily debugged.

One potential security loophole is the need to put the password in the print file, since anyone with access to that print file could then obtain your password. If your application deletes the print files as soon as they are sent, this is not a problem. But if it leaves them archived, you should consider encrypting the password using the MX_PWCRYPT function (see comments below). The encrypted password can be inserted directly into the //PDFX,Email.SMTP.Password,xxxxxx directive, either in ASCII or comma-delimited decimal format, e.g.:

//PDFX.Email.SMTP.Username,jamesbond

//;unencrypted password:

//PDFX,Email.SMTP.Password,secret

//;mode 2 encryption, decimal format

//PDFX,Email.SMTP.Password,2,118,123,74,97,110,86

//;mode 3 encryption, ASCII format (* starts with chr(3) leadin)

//PDFX,Email.SMTP.Password,Cn6FZEHA25zoVKkc8xWMiciZwPVrPDp1vgIzNrCLP/6rbqAuKdNNpwdi0xswA2JgDNnq/

If the SMTP server requires OAUTH2 authentication, you'll need to use XCALL OAUTH2 to first obtain (and perhaps refresh) an access token (independent of PDFX, probably using XCALL OAUTH2), and then specify it in the Email.SMTP.Password directive, preceded by the prefix "[oauth2]", for example:

//PDFX,Email.SMTP.Password,[oauth2]ya29.a0AfB_byBunmfPUnJuV0XI5i...

Comments

To encrypt your password, use the MX_PWCRYPT function (which see in the A-Shell Reference manual). For mode 2 encryption, it’s best to use the comma-delimited decimal format as shown above. (The raw encrypted string in ASCII format may contain troublesome control characters such as CR or LF.) For the more secure mode 3 encryption, omit the key parameter and specify the SMTP.Username value as for the seed parameter. (Make sure the SMTP.Username directive appears before the SMTP.Password directive in the print file.) The encryption result will be a 69 character string starting with chr(3) which can be used directly as the value of the SMTP.Password property. (Depending on your editor, the chr(3) character may show up as a dim “C”, or perhaps as “<ETX>”. If it gets lost or corrupted in the process of copying/pasting it, you can enter chr(3) into VUE with the sequence Ctrl+G, Ctrl+C. For other Windows-style editors, you can use ALT+003. If in doubt, DUMP the file in hex mode to confirm that the first character really is an ASCII 3.)

Compatibility

PDFXv3, v5, v9. The comma-delimited decimal format for the password requires A-Shell build 1241+. The mode 3 encrypted password support was added in A-Shell build 1385.

OAUTH2 authentication requires ASNHET.DLL (or libashnet.so) 1.14.191 or later.