| Help for Alpine - GRAPH |
| You are in Home > Miscellaneous > GRAPH |
GRAPH is a Microsoft® service that can be used to access services such as your Outlook email in the server. A GRAPH application requests permissions from a user to access resources in the server on behalf of that user. There are many issues that need to be understood before using GRAPH and these will be explained here, but before we get there, let us start by showing the relevant configurations that are needed in Alpine.
First, the name of the server is graph.microsoft.com. A valid configuration for your inbox-path is
inbox-path = {graph.microsoft.com/graph/user=YourId@outlook.com}INBOX
Note that your username is just your email account, which could be your personal account, or your work or school account.
You will notice that there is no "/ssl" flag in the definition of the inbox-path, not because the connection to the server is insecure, but because a secure connection is required, so in order to enforce this, "/ssl" is set implicitly on your behalf. Another part that is not explicit is the method of authentication. The default is "/auth=OAUTHBEARER" and cannot be changed, as it is a requirement of Microsoft.
GRAPH does not use SMTP, so you do not need to configure the smtp-server variable to send emails. That does not mean that you cannot use an SMTP service as a way to send emails, but if you want to use the GRAPH server to send your emails, you will need to configure a different variable, not an SMTP server. The variable you need to configure is called other-sending-server, and is configured in a similar way to that of the inbox-path, namely
other-sending-server=graph.microsoft.com/graph/user=YourId@outlook.com
Once you configure the previous variable it is assumed that you intend to use it instead of the smtp-server variable, so the value of the SMTP server variable will be ignored as soon as you configure this variable.
This is the way this looks in the configuration screen:
Inbox Path = {graph.microsoft.com/graph/user=YourId@outlook.com}INBOX
SMTP Server = this.does.not.matter/it.is.ignored
Other Sending Server = graph.microsoft.com/graph/user=YourId@outlook.com
Finally, in order to read your email in other folders in the server, you need to add
folder-collections=Outlook {graph.microsoft.com/graph/user=YourId@outlook.com}[]
in your configuration file.
Alpine users are accustomed to accessing email either as a local folder in some standard format, or online either through IMAP or POP3. GRAPH access is different. When you are reading your email in a GRAPH folder you are reading your email over HTTPS Version 1.1. This implies that most of the access of your folders is offline, not online. Every operation will require opening a connection to the server, login in, requesting the resource, receiving the resource, parsing it, and finally displaying it to the user. The actual connection to the server is only open briefly, so for the most part of your interaction with a GRAPH folder you are most likely offline, except at some very specific moments.
Alpine implements checks for new mail in the server. This means every so often Alpine will connect to the GRAPH server to check for new mail, but at other times it will not be connected to the server at all. This is different than in an IMAP folder where the connection remains open and commands are sent and information is received though that connection. If the connection to an IMAP server ever fails, you need to restart the full connection again. In GRAPH you are keeping the connection closed and only open it when needed. Alpine will give the appearance that it is connected to the server at all times, but that is just an appearance, in realiy it is connecting only as needed.
You may be surprised to read that GRAPH access is not the same as email access. If you have access to Outlook in your favorite web browser, you are accessing email through GRAPH, and that is different than accessing an email server in many ways.
Later on we will talk about how to display accurate information in the index.
The idea of the implementation in Alpine of a GRAPH interface is to imitate your experience accessing a folder through IMAP. As you can deduce from the previous text, the default GRAPH experience is not set up for that, so sometimes a price in delay to complete an operation must be paid to match the expectation of an Alpine user.
You may create and delete folders in the GRAPH server in the normal way that you do it in a collection. GRAPH supports creation of child folders, and Alpine supports that, but in a way that is not 100% compatible with GRAPH. For example, in GRAPH you can have a folder "Test" with a child folder "Child Test". In Alpine you would see the folder "Test" followed by a slash (or solidus), "Test/". Selecting "Test" would open the folder, and selecting the slash "/" would show the list of subfolders in a new screen, among which you would see "Child Test".
Given that Alpine uses the slash character "/" to separate folders from their childs, Alpine has problems with folders that contain this character in their names. Try not to use this character in naming a folder.
Unless you expunge a message, marking a message for deletion will do nothing. This is because a GRAPH server does not have a two step deletion process as IMAP does. Once a message is expunged, it is removed permanently.
In addition, Alpine can only expunge up to twenty (20) messages at the time. If there are more messages to be expunged alpine will repeat the expunge request until all deleted messages have been expunged. The restriction of not being able to expunge more than twenty messages at the time comes from a restriction in GRAPH. Technically one can expunge one message at the time, but this would mean twenty connections to expunge twenty messages. To address this, Alpine uses a batch operation, which allows it to send up to twenty requests for deleting messages at one time, and this is a limit imposed by Microsoft for batch requests.
Copying messages is strange. You cannot copy messages whose destination is a GRAPH folder, unless it is done among folders in the same account in the GRAPH server. You may save a message from a GRAPH folder to a local or IMAP folder, but you cannot do the opposite. However, you can copy a message from your INBOX to your Junk messages folders in the same account. When a message is copied between GRAPH folders in the same, copying is done in batches of up to 20 messages, just like expunging above.
Upon opening a folder, Alpine displays envelope information in the screen. Since GRAPH does not have information on message numbers, the information that is given to us that allows us to identify a message is what is called a message id, which is a very long string that identifies the message uniquely in the folder. In GRAPH you can ask for the id of the 5th message, but if you only have the id of the message, you cannot know if it is the 5th message, the first, or the last.
Internally Alpine has to open two connections to the server before it displays any information to the user: The first connection gets metadata about the folder the user is opening. This provides information on the number of messages and the number of unread messages, as well as the folder id. The second connection downloads the necessary information to display the index screen. If you are using the /loser flag this will slow down Alpine significantly, otherwise, depending on if the feature Graph Downloads Envelopes Only is enabled, this could be done very quickly.
The next step consists in syncrhonizing the information about the folder in Alpine and the server. In essence the idea is that once a user opens the folder, any differences, such as arrival of new messages, messages expunged from the folder, or changes in status of a message should be reported to the message. The GRAPH server determines, based on what has been exchanged so far, what has to be sent in order to start sending information on new messages, and so forth. GRAPH servers call this a delta, and it has to be done three times. To speed transfer of information, Alpine requests that information of only one message be sent. After this Alpine receives the go ahead from the server to keep asking for deltas, and all are done quickly on a fast connection. These kind of synchronization takes the same amount of time, regardless of if you are using the /loser flag or not, or if you are downloading envelopes only or not. To learn more read what the /loser flag does.
Alpine does not cache externally any information about the messages in a folder. That is, once you close the folder (or Alpine) all that information is lost and to recover it you must reopen the folder. This means that if an operation took long to complete, the next time you reopen the folder you should expect it will take a long time to complete again. However, once an operation has completed in the folder, regardless of how long it took, the information will be cached and you will not need to wait for a long time the next time you repeat the same operation. For example, if the index screen takes a long time to update, the next time you go back to that exact index screen it will be painted immediately.
Based on the previous information, if you ever get asked about closing a connection due to a long timeout, think twice about closing the connection. The recommendation is to keep the connection open when asked about closing the connection to a GRAPH server, if the timeout is ocassional. Of course, if you voluntarily close a folder, all the information about the messages in the folder is lost and is not used the next time the folder is reopened.
Normally the /loser flag is a way in which users tell Alpine that certain operations are not being done correctly by the server, and would prefer that Alpine did such operation instead. A case like this is when a search is being performed. This normally requires that Alpine downloads all the information that is needed for the search. This is a case in which users sacrifice speed over accuracy.
In a GRAPH folder the /loser flag is not meant to be used in the same way. Searches will always be done by the GRAPH server. Instead the /loser flag sacrifices speed for accuracy in the way the message is displayed.
Adding the /loser flag to your inbox-path will make Alpine download the full message before displaying an entry in the index for it. You will see the message as it was intended to be displayed with all of its attachments. Doing this will slow down Alpine, but you gain in accuracy. Even the correct size of the message is displayed in the screen! You pay in time, but you get accuracy.
The other implication is that not using the /loser flag makes Alpine gain speed. Operations might not be done totally right, but they are done quickly and most times the gain in speed will not imply a loss of accuracy. Without the /loser flag, Alpine does not take very long to display the index screen, and a delay might be noticed when a message is viewed. If you use the /loser flag, once a message is downloaded it opens immediately.
Even if you do not use the /loser flag, Alpine will stil download the full message if this is an invitation to an event, so you will be able to read the details of the event in Alpine. As it was said earlier, doing this slows down Alpine, but it is hoped that the delay is not significant because invitations to events are typically small.
If you decide to use the /loser flag for a folder in GRAPH, and your folder is an incoming folder, consider adding your folder to the list of Stayopen folders as this will minimize the number of times that you will reload the information from the server since the folder will be kept open even when you go to another folder.
This option controls if at the time you open a GRAPH folder, if Alpine will download envelope information only (such as the To, From, Subject, etc. headers) or if it will download all the headers of the message previous to displaying the index screen. The default is that Alpine will download the envelopes only, but if you disable this feature, Alpine will download all the headers of a message previous to displaying the index screen.
Having said that, if you configure your GRAPH account with the /loser flag then this option will have no effect, and adding the /loser flag will make Alpine the slowest possible.
There are tradeoffs of speed versus accuracy that you have to understand when configuring this option, or using the /loser flag.
When you use a GRAPH server, Alpine will connect to the server every time it needs to download information. Some information is onerous to get, so to provide you with accurate information you would have to slow down your experience in Alpine. Depending on your speed connection, that might be a considerable amount.
This feature allows you to experiment and control how slow your experience might be. There are three speeds at which Alpine can be configured to run. If you configured Alpine to use the /loser flag, this option will be ignored.
Unlike other email services, in a GRAPH server a client such as Alpine can only display the PLAIN text or the HTML text in a message, so users have to choose the part they wish to read before opening the message.
By default a GRAPH servere serves the HTML text part. Setting this feature will cause the GRAPH server to serve the PLAIN text part instead, and unsetting it to serve the HTML text part, or the PLAIN text part if there is no HTML part.
Note that in some modern email systems HTML email is sometimes the only part that is sent, and no PLAIN text part is sent. Alpine can display HTML email, or you can send your message to an external browser with the e"X"ternal command, so setting this feature might make you lose some information. This is just one of the differences between a GRAPH server and a POP3 or IMAP server.
You can make Alpine treat a GRAPH server as a POP3 server in the sense that when reading a message the full message must be downloaded before displaying it, and you will be able to choose reading both the PLAIN and HTML parts, if available. This will slow down Alpine if a message contains many or large attachments, or inline images in a HTML part. In order to gain this control add "/loser" to the value of the server, so instead of using the value
you would type
| You are in Home > Miscellaneous > GRAPH |