When mail fails
A wrong password, a typo in the server name, a provider that blocks programs: a mail program meets more trouble than most. This recipe sends a test mail and, when it doesn't work, tells the player in plain words what to fix – the program to try first when you set up mail.
Functions: the errors of c0de net, SMTP_SEND, IMAP_CREATE, and HAS_SECRET of c0de/security
What you need
The mod c0de net, your mail account and app password as in Mail from the farm, a trigger block with a button, a laptop, and variable items server (STRING) and port (INTEGER). For the exercise, the IMAP server of The order desk.
The idea
The functions of c0de_net/mail raise an error when something goes wrong. A CALL with an ERROR variable catches it, and its code says what happened:
| Code | Name | What happened | What to do |
|---|---|---|---|
| 309 | INVALID_ARGUMENT | no server or sender, an address that isn't one, unknown criteria | fix the program |
| 311 | PERMISSION_DENIED | a connection to port 25 | use port 465 or 587 of your provider |
| 1001 | CLIENT_UNAVAILABLE | the player isn't online or has no c0de net | nothing, try later |
| 1003 | REQUEST_FAILED | no connection: unknown server, refused, a certificate problem | check server, port and security |
| 1004 | REQUEST_TIMEOUT | the server didn't answer in time | try again later |
| 1005 | RESPONSE_TOO_LARGE | IMAP_FETCH would read too much | fetch fewer messages, or without text |
| 1006 | MAIL_DISABLED | the server or the player has switched mail off | ask the administrator, or allowMail=true |
| 1007 | AUTHENTICATION_FAILED | the user name or the password is wrong | use an app password |
| 1008 | MAIL_REJECTED | the mail server refused, e.g. a recipient or a folder | read the message of the error |
| 1009 | MAIL_LIMIT | too many recipients, too much text, too many mails a minute | send less, or wait a minute |
INVALID_ARGUMENT and PERMISSION_DENIED are constants of c0de; the others come with INCLUDE c0de_net/mail, as c0de_net/mail/AUTHENTICATION_FAILED and so on.
Most problems of a new mail program are AUTHENTICATION_FAILED: many providers don't let programs in with the password of the account. In the security settings of your account, create an app password for c0de and use that one.
The program
PROGRAM mailcheck
NOOP
INCLUDE c0de/security
INCLUDE c0de/strings
INCLUDE c0de_net/mail
NOOP
FUNCTION explain
PARAMETER code INTEGER
RESULT text STRING
BEGIN
ASSIGN text "Unexpected error " ⊕ code ;
IF code = INVALID_ARGUMENT ;
BEGIN
ASSIGN text "Check the server, the sender and the addresses" ;
END IF
IF code = PERMISSION_DENIED ;
BEGIN
ASSIGN text "Port 25 is blocked, use 465 or 587" ;
END IF
IF code = c0de_net/mail/CLIENT_UNAVAILABLE ;
BEGIN
ASSIGN text "Nobody with c0de net is online" ;
END IF
IF code = c0de_net/mail/MAIL_DISABLED ;
BEGIN
ASSIGN text "Mail is switched off" ;
END IF
IF code = c0de_net/mail/AUTHENTICATION_FAILED ;
BEGIN
ASSIGN text "Wrong user or password (an app password?)" ;
END IF
IF code = c0de_net/mail/MAIL_REJECTED ;
BEGIN
ASSIGN text "The mail server refused it" ;
END IF
IF code = c0de_net/mail/MAIL_LIMIT ;
BEGIN
ASSIGN text "Too much mail: send less or wait a minute" ;
END IF
IF code = c0de_net/mail/REQUEST_FAILED ;
BEGIN
ASSIGN text "The mail server can't be reached" ;
END IF
IF code = c0de_net/mail/REQUEST_TIMEOUT ;
BEGIN
ASSIGN text "The mail server is too slow" ;
END IF
END FUNCTION
NOOP
FUNCTION account
PARAMETER server STRING
PARAMETER port INTEGER
RESULT smtp STRUCT c0de_net/mail/SMTP_SERVER
BEGIN
SECRET mailPassword STRING
ASSIGN smtp.server server ;
ASSIGN smtp.port port ;
ASSIGN smtp.security "tls" ;
ASSIGN smtp.user "steve@example.com" ;
ASSIGN smtp.password mailPassword ;
ASSIGN smtp.from "Farm computer <steve@example.com>" ;
ASSIGN smtp.timeout 10 ;
END FUNCTION
NOOP
FUNCTION send
PARAMETER server STRING "smtp.example.com"
PARAMETER port INTEGER 0
PARAMETER to STRING "steve@example.com"
PARAMETER lines INTEGER 3
BEGIN
VARIABLE known BOOLEAN
VARIABLE smtp STRUCT c0de_net/mail/SMTP_SERVER
VARIABLE problem ERROR
VARIABLE text STRING
VARIABLE message STRING
VARIABLE nl CHAR
CALL CLS
CALL c0de/security/HAS_SECRET
PARAMETER name "mailPassword" ;
RESULT result known
IF NOT known ;
BEGIN
CALL PRINT
PARAMETER value "Put your password into the vault first" ;
EXIT 2 ;
END IF
CALL account
PARAMETER server server ;
PARAMETER port port ;
RESULT smtp smtp
CALL c0de/strings/CHR
PARAMETER code 10 ;
RESULT result nl
FOR i INTEGER 1 ; lines ;
BEGIN
ASSIGN text text ⊕ "Line " ⊕ i ⊕ ": the farm is fine." ⊕ nl ;
END FOR
CALL c0de_net/mail/SMTP_SEND problem
PARAMETER server smtp ;
PARAMETER to to ;
PARAMETER subject "A test from the farm" ;
PARAMETER text text ;
IF problem.code ≠ 0 ;
BEGIN
CALL explain
PARAMETER code problem.code ;
RESULT text message
CALL PRINT
PARAMETER value message ;
EXIT 1 ;
END IF
CALL PRINT
PARAMETER value "Sent to " ⊕ to ;
END FUNCTIONBuilding and running it
- Set the trigger block to
mailcheck/send, put your variable itemsserverandportinto it, and bind the laptop to it. - Press the button. If everything is right, the laptop shows
Sent to steve@example.com– use your own address forto– and a test mail arrives. - Now break it on purpose, one thing at a time, and watch the laptop:
| You change | The laptop shows | Exit code |
|---|---|---|
| the vault is empty or closed | Put your password into the vault first | 2 |
| a wrong password in the vault | Wrong user or password (an app password?) | 1 |
server to smtp.nothing.invalid | The mail server can't be reached | 1 |
port to 25 | Port 25 is blocked, use 465 or 587 | 1 |
to to nobody | Check the server, the sender and the addresses | 1 |
lines to 3000 | Too much mail: send less or wait a minute | 1 |

How it works
explainturns a code into words, like in When the network fails: it starts with a message for unknown codes and overwrites it for every code it knows.- HAS_SECRET asks the vault first. A SECRET line for a missing secret raises SECRET_NOT_FOUND and stops the program, so
sendonly callsaccount, which has the SECRET line, when the password is there. Without an open vault, HAS_SECRET says FALSE as well. accountreturns the SMTP_SERVER as a result, so the password lives only inside it and in the struct. Itstimeoutof 10 seconds lets a test fail fast instead of waiting the full 30.- The FOR loop writes
lineslines of text. 3000 lines are about 90 KiB, more than the 64 KiB a message may have: SMTP_SEND raises MAIL_LIMIT before it connects. Too many recipients or more than 10 mails a minute raise it as well. - The exit codes are 0 for sent, 1 for an error of the mail and 2 for a missing password, so a comparator next to the trigger block can show them.
Unlike in When the network fails, there is no retry: most mail errors don't go away by themselves, and a retry of SMTP_SEND that timed out might send the message twice.
Try it yourself
- The folder program of a friend crashes when the folder exists already. Catch it.
Solution
PROGRAM newfolder
NOOP
INCLUDE c0de_net/mail
NOOP
FUNCTION create
PARAMETER server STRING "imap.example.com"
PARAMETER port INTEGER 0
PARAMETER name STRING "Orders"
BEGIN
SECRET mailPassword STRING
VARIABLE imap STRUCT c0de_net/mail/IMAP_SERVER
VARIABLE problem ERROR
ASSIGN imap.server server ;
ASSIGN imap.port port ;
ASSIGN imap.user "steve@example.com" ;
ASSIGN imap.password mailPassword ;
CALL CLS
CALL c0de_net/mail/IMAP_CREATE problem
PARAMETER server imap ;
PARAMETER folder name ;
IF problem.code = c0de_net/mail/MAIL_REJECTED ;
BEGIN
CALL PRINT
PARAMETER value "The server refused: " ⊕ name ⊕ " exists already?" ;
EXIT 1 ;
END IF
IF problem.code ≠ 0 ;
BEGIN
CALL PRINT
PARAMETER value problem.message ;
EXIT 2 ;
END IF
CALL PRINT
PARAMETER value "Created " ⊕ name ;
END FUNCTIONIMAP_CREATE raises MAIL_REJECTED for a folder that exists – the mail server refuses the command. The program says so and ends with exit code 1. With the name Invoices, it shows Created Invoices. Every other error ends with its message and exit code 2.
- Alex has set
allowMail=falsein their game. What happens when Alex presses the button? And what when a timer block starts the program on a trigger block that Alex owns?
Solution
Both times, the laptop shows Mail is switched off: MAIL_DISABLED. The mail would go out from Alex's computer – when Alex presses the button, because Alex started the process, and from the timer block, because a process that nobody started runs as the owner of the trigger block. When Steve presses the button, the mail goes out from Steve's computer and works. An administrator who sets enableMail=false in config/c0de_net.properties switches mail off for everybody.
Read more
- Errors of c0de net
- Settings of c0de net
- Errors in the programmer path
- Exit codes