(PureBasic) Emails with Related Items that have "Attachment" Content-Disposition

Emails are MIME, and an email with attachments or HTML images are multipart MIME. The MIME parts that are items to be displayed inline within an HTML email are called "related" items. Typically they are images. They are situationed under the "multipart/related" MIME umbrella. Attachments are semantically those files that are attached to an email but typically not displayed inline. They are located under the "multipart/mixed" MIME umbrella.

However, related items and attachments aren't always mutually exclusive. Chilkat considers the semantics of the any individual item, not just the placement within the MIME. Also, many software systems create emails in non-standard ways. There are innumerable ways (going against customary "standards") that multipart MIME can be constructed.

For example, if a MS-Word document is located under a multipart/related, but also the MIME sub-header indicates "attachment", then the MS-Word document would be both a related item and an attachment. This is because some email clients are capable of displaying MS-Word docs inline, but also it's semantically an attachment, because in most cases the MS-Word document is expected to be saved to disk.

Here's a sample MIME sub-header. (You can open .eml files in a text editor to see the MIME headers and sub-headers. If you're not familiar with MIME, ask ChatGPT to explain the basics.)

------=_Part_2795453_726600066.1721122066159
Content-Type: application/octet-stream; name="abcd.docx"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="abcd.docx"

Note: This example requires Chilkat v10.0.0 or greater.

Chilkat PureBasic Module Download Chilkat PureBasic Module

IncludeFile "CkEmail.pb"

Procedure ChilkatExample()

    email.i = CkEmail::ckCreate()
    If email.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    ; Load an email with a MS-Word (docx) MIME part that is considered both a related item and an attachment:
    ; 
    ; ... 
    ; ------=_Part_2795453_726600066.1721122066159
    ; Content-Type: application/octet-stream; name="abcd.docx"
    ; Content-Transfer-Encoding: base64
    ; Content-Disposition: attachment; filename="abcd.docx"
    ; ...
    ; 
    success.i = CkEmail::ckLoadEml(email,"qa_data/eml/related_item_with_disposition_attachment.eml")
    If success <> 1
        Debug CkEmail::ckLastErrorText(email)
        CkEmail::ckDispose(email)
        ProcedureReturn
    EndIf

    ; Examine related items and attachments:
    Debug "Num Related Items: " + Str(CkEmail::ckNumRelatedItems(email))
    Debug "Num Attachments: " + Str(CkEmail::ckNumAttachments(email))

    ; In our example file, we already know it has 1 related item, and 1 attachment,
    ; and they are both the same MS-Word document.
    ; To simplify for the example, we just get the info for the 1st without checking..
    Debug "Related filename: " + CkEmail::ckGetRelatedFilename(email,0)
    Debug "Attachment filename: " + CkEmail::ckGetAttachmentFilename(email,0)

    ; The filename is "abcd.docx" in both cases.

    ; Get the Content-Disposition header field.
    ; Note: The GetRelatedHeader method is added in Chilkat v10.0.0
    disposition.s = CkEmail::ckGetRelatedHeader(email,0,"Content-Disposition")
    If CkEmail::ckLastMethodSuccess(email) = 0
        Debug CkEmail::ckLastErrorText(email)
        CkEmail::ckDispose(email)
        ProcedureReturn
    EndIf

    Debug "Content-Disposition: " + disposition

    ; Sample output:

    ; Num Related Items: 1
    ; Num Attachments: 1
    ; Related filename: abcd.docx
    ; Attachment filename: abcd.docx
    ; Content-Disposition: attachment; filename="abcd.docx


    CkEmail::ckDispose(email)


    ProcedureReturn
EndProcedure