Diese Seite auf Deutsch

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:

CodeNameWhat happenedWhat to do
309INVALID_ARGUMENTno server or sender, an address that isn't one, unknown criteriafix the program
311PERMISSION_DENIEDa connection to port 25use port 465 or 587 of your provider
1001CLIENT_UNAVAILABLEthe player isn't online or has no c0de netnothing, try later
1003REQUEST_FAILEDno connection: unknown server, refused, a certificate problemcheck server, port and security
1004REQUEST_TIMEOUTthe server didn't answer in timetry again later
1005RESPONSE_TOO_LARGEIMAP_FETCH would read too muchfetch fewer messages, or without text
1006MAIL_DISABLEDthe server or the player has switched mail offask the administrator, or allowMail=true
1007AUTHENTICATION_FAILEDthe user name or the password is wronguse an app password
1008MAIL_REJECTEDthe mail server refused, e.g. a recipient or a folderread the message of the error
1009MAIL_LIMITtoo many recipients, too much text, too many mails a minutesend 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 ​

c0de
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 FUNCTION

Building and running it ​

  1. Set the trigger block to mailcheck / send, put your variable items server and port into it, and bind the laptop to it.
  2. Press the button. If everything is right, the laptop shows Sent to steve@example.com – use your own address for to – and a test mail arrives.
  3. Now break it on purpose, one thing at a time, and watch the laptop:
You changeThe laptop showsExit code
the vault is empty or closedPut your password into the vault first2
a wrong password in the vaultWrong user or password (an app password?)1
server to smtp.nothing.invalidThe mail server can't be reached1
port to 25Port 25 is blocked, use 465 or 5871
to to nobodyCheck the server, the sender and the addresses1
lines to 3000Too much mail: send less or wait a minute1
the laptop showing "Wrong user or password (an app password?)" next to the trigger block of mailcheck

How it works ​

  • explain turns 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 send only calls account, which has the SECRET line, when the password is there. Without an open vault, HAS_SECRET says FALSE as well.
  • account returns the SMTP_SERVER as a result, so the password lives only inside it and in the struct. Its timeout of 10 seconds lets a test fail fast instead of waiting the full 30.
  • The FOR loop writes lines lines 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 ​

  1. The folder program of a friend crashes when the folder exists already. Catch it.
Solution
c0de
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 FUNCTION

IMAP_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.

  1. Alex has set allowMail=false in 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 ​