First, I'm glad to hear you are trying the mail service. Here are some guidelines for interpreting a mail message:
-
You can get a mail message in either JSON (the default) or MIME format. The JSON representation is structurally very similar to MIME, so you should become familiar with MIME if you aren't already.
-
The attached ZIP contains two files. Both files represent the same message -- sample.eml is in MIME format and sample.json is (of course) in JSON format. This message contains rich text, an embedded image and an attachment. To see what I mean, you can open the .eml directly in Notes (and most other email clients).
-
If you are building a web application in JavaScript or a native mobile application, you may not have a MIME parser available. That's why we provide JSON format by default, but you should decide which format is best for your application.
-
The message body is a flat array of parts, but logically each multipart actually contains subparts. For example, the sample message starts with a multipart/mixed part. Logically, this contains a multipart/related part and an attachment (domino.gif). The multipart/related part also contains subparts, etc.
-
In general you want to scan for either a text/plain part or a text/html part to render in your application. In the sample, there is a multipart/alternative part that contains both text/html and text/plain. The text/plain part contains the same data as the text/html part, but text/plan is lower fidelity. For example, it doesn't contain rich text formatting.
-
The semantics of multipart/related are a little more complicated. Basically, it's a way of embedding images in a message and having the HTML part refer to the image by content ID. You should definitely consult the MIME specs for more background.
I know that's a very high level overview. If you have more questions, post them here and I will try to help.
-- Dave Delay