GMimeMessage: GMime 3.0 Reference Manual

## GMimeMessage

GMimeMessage — Messages

## Functions

GMimeMessage * | g_mime_message_new ()
InternetAddressList * | g_mime_message_get_sender ()
InternetAddressList * | g_mime_message_get_from ()
InternetAddressList * | g_mime_message_get_reply_to ()
InternetAddressList * | g_mime_message_get_to ()
InternetAddressList * | g_mime_message_get_cc ()
InternetAddressList * | g_mime_message_get_bcc ()
void | g_mime_message_add_mailbox ()
InternetAddressList * | g_mime_message_get_addresses ()
InternetAddressList * | g_mime_message_get_all_recipients ()
void | g_mime_message_set_subject ()
const char * | g_mime_message_get_subject ()
void | g_mime_message_set_date ()
GDateTime * | g_mime_message_get_date ()
void | g_mime_message_set_message_id ()
const char * | g_mime_message_get_message_id ()
void | g_mime_message_set_mime_part ()
GMimeObject * | g_mime_message_get_mime_part ()
void | g_mime_message_foreach ()
GMimeObject * | g_mime_message_get_body ()
GMimeAutocryptHeader * | g_mime_message_get_autocrypt_header ()
GMimeAutocryptHeaderList * | g_mime_message_get_autocrypt_gossip_headers_from_inner_part ()
GMimeAutocryptHeaderList * | g_mime_message_get_autocrypt_gossip_headers ()

## Types and Values

enum | GMimeAddressType
struct | GMimeMessage

## Object Hierarchy

        GObject
        ╰── GMimeObject
            ╰── GMimeMessage

## Description

A GMimeMessage represents an rfc822 message.

## Functions

### g_mime_message_new ()

    GMimeMessage *
    g_mime_message_new (gboolean pretty_headers);

If `pretty_headers` is `TRUE`, then the standard rfc822 headers are initialized so as to put headers in a nice friendly order. This is strictly a cosmetic thing, so if you are unsure, it is safe to say no (`FALSE`).

#### Parameters

pretty_headers | make pretty headers |

#### Returns

an empty GMimeMessage object.

### g_mime_message_get_sender ()

    InternetAddressList *
    g_mime_message_get_sender (GMimeMessage *message);

Gets the parsed list of addresses in the Sender header.

#### Parameters

message | A GMimeMessage |

#### Returns

the parsed list of addresses in the Sender header.

[transfer none]

### g_mime_message_get_from ()

    InternetAddressList *
    g_mime_message_get_from (GMimeMessage *message);

Gets the parsed list of addresses in the From header.

#### Parameters

message | A GMimeMessage |

#### Returns

the parsed list of addresses in the From header.

[transfer none]

### g_mime_message_get_reply_to ()

    InternetAddressList *
    g_mime_message_get_reply_to (GMimeMessage *message);

Gets the parsed list of addresses in the Reply-To header.

#### Parameters

message | A GMimeMessage |

#### Returns

the parsed list of addresses in the Reply-To header.

[transfer none]

### g_mime_message_get_to ()

    InternetAddressList *
    g_mime_message_get_to (GMimeMessage *message);

Gets combined list of parsed addresses in the To header(s).

#### Parameters

message | A GMimeMessage |

#### Returns

the parsed list of addresses in the To header(s).

[transfer none]

### g_mime_message_get_cc ()

    InternetAddressList *
    g_mime_message_get_cc (GMimeMessage *message);

Gets combined list of parsed addresses in the Cc header(s).

#### Parameters

message | A GMimeMessage |

#### Returns

the parsed list of addresses in the Cc header(s).

[transfer none]

### g_mime_message_get_bcc ()

    InternetAddressList *
    g_mime_message_get_bcc (GMimeMessage *message);

Gets combined list of parsed addresses in the Bcc header(s).

#### Parameters

message | A GMimeMessage |

#### Returns

the parsed list of addresses in the Bcc header(s).

[transfer none]

### g_mime_message_add_mailbox ()

    void
    g_mime_message_add_mailbox (GMimeMessage *message,
                                GMimeAddressType type,
                                const char *name,
                                const char *addr);

Add a mailbox of a chosen type to the MIME message.

Note: The `name` (and `addr` ) strings should be in UTF-8.

#### Parameters

message | A GMimeMessage |
type | A GMimeAddressType |
name | The name of the mailbox (or `NULL`) |
addr | The address of the mailbox |

### g_mime_message_get_addresses ()

    InternetAddressList *
    g_mime_message_get_addresses (GMimeMessage *message,
                                  GMimeAddressType type);

Gets a list of addresses of the specified `type` from the `message` .

#### Parameters

message | A GMimeMessage |
type | A GMimeAddressType |

#### Returns

a list of addresses of the specified `type` from the `message` .

[transfer none]

### g_mime_message_get_all_recipients ()

    InternetAddressList *
    g_mime_message_get_all_recipients (GMimeMessage *message);

Gets the complete list of recipients for `message` .

#### Parameters

message | A GMimeMessage |

#### Returns

a newly allocated InternetAddressList containing all recipients of the message or `NULL` if no recipients are set.

[transfer full]

### g_mime_message_set_subject ()

    void
    g_mime_message_set_subject (GMimeMessage *message,
                                const char *subject,
                                const char *charset);

Set the subject of a `message` .

Note: The `subject` string should be in UTF-8.

#### Parameters

message | A GMimeMessage |
subject | Subject string |
charset | The charset to use for encoding the subject or `NULL` to use the default |

### g_mime_message_get_subject ()

    const char *
    g_mime_message_get_subject (GMimeMessage *message);

Gets the subject of the `message` .

#### Parameters

message | A GMimeMessage |

#### Returns

the subject of the `message` in a form suitable for display or `NULL` if no subject is set. If not `NULL`, the returned string will be in UTF-8.

[nullable]

### g_mime_message_set_date ()

    void
    g_mime_message_set_date (GMimeMessage *message,
                             GDateTime *date);

Sets the Date header on a MIME Message.

#### Parameters

message | A GMimeMessage |
date | a date to be used in the Date header |

### g_mime_message_get_date ()

    GDateTime *
    g_mime_message_get_date (GMimeMessage *message);

Gets the parsed date and time value from the Date header.

#### Parameters

message | A GMimeMessage |

#### Returns

a GDateTime on success or `NULL` if the date could not be parsed.

[nullable][transfer none]

### g_mime_message_set_message_id ()

    void
    g_mime_message_set_message_id (GMimeMessage *message,
                                   const char *message_id);

Set the Message-Id on a message.

#### Parameters

message | A GMimeMessage |
message_id | message-id (addr-spec portion) |

### g_mime_message_get_message_id ()

    const char *
    g_mime_message_get_message_id (GMimeMessage *message);

Gets the Message-Id header of `message` .

#### Parameters

message | A GMimeMessage |

#### Returns

the Message-Id of a message, or `NULL` if not specified.

[nullable]

### g_mime_message_set_mime_part ()

    void
    g_mime_message_set_mime_part (GMimeMessage *message,
                                  GMimeObject *mime_part);

Set the root-level MIME part of the message.

#### Parameters

message | A GMimeMessage |
mime_part | The root-level MIME Part |

### g_mime_message_get_mime_part ()

    GMimeObject *
    g_mime_message_get_mime_part (GMimeMessage *message);

Gets the toplevel MIME part contained within `message` .

#### Parameters

message | A GMimeMessage |

#### Returns

the toplevel MIME part of `message` , or `NULL` if none is present.

[nullable][transfer none]

### g_mime_message_foreach ()

    void
    g_mime_message_foreach (GMimeMessage *message,
                            GMimeObjectForeachFunc callback,
                            gpointer user_data);

Recursively calls `callback` on each of the mime parts in the mime message.

#### Parameters

message | A GMimeMessage |
callback | function to call on each of the mime parts contained by the mime message. | [scope call]
user_data | user-supplied callback data |

### g_mime_message_get_body ()

    GMimeObject *
    g_mime_message_get_body (GMimeMessage *message);

Attempts to identify the MIME part containing the body of the message.

#### Parameters

message | A GMimeMessage |

#### Returns

a GMimeObject containing the textual content that appears to be the main body of the message, or `NULL` if no body part has been set.

Note: This function is NOT guaranteed to always work as it makes some assumptions that are not necessarily true. It is recommended that you traverse the MIME structure yourself.

[nullable][transfer none]

### g_mime_message_get_autocrypt_header ()

    GMimeAutocryptHeader *
    g_mime_message_get_autocrypt_header (GMimeMessage *message,
                                         GDateTime *now);

Creates a new GMimeAutocryptHeader based on the relevant Autocrypt header associated with the sender of an e-mail message.

If the message has no sender in the From: field, or has more than one sender, then this function will return `NULL`. Autocrypt should ignore the message entirely.

If there is one sender, but no single Autocrypt header is found that matches that e-mail address, a GMimeAutocryptHeader will be returned for the sender, but it will be incomplete (see g_mime_autocrypt_header_is_complete).

Note that the following types of Autocrypt headers will not be returned by this function:

- headers that do not match an address in "From:"

- unparseable headers

- headers with unknown critical attributes

- duplicate valid headers for the sender's address

The returned Autocrypt header will have its effective_date set to the earliest of either:

- the Date: header of the message or

- `now` (or the current time, if `now` is `NULL`)

#### Parameters

message | a GMimeMessage object. |
now | a GDateTime object, or `NULL` |

#### Returns

a new GMimeAutocryptHeader object, or `NULL` if the message should be ignored for purposes of Autocrypt.

[nullable][transfer full]

### g_mime_message_get_autocrypt_gossip_headers_from_inner_part ()

    GMimeAutocryptHeaderList *
    g_mime_message_get_autocrypt_gossip_headers_from_inner_part
                                   (GMimeMessage *message,
                                    GDateTime *now,
                                    GMimeObject *inner_part);

Creates a new GMimeAutocryptHeaderList of relevant headers of the given type based on the recipient(s) of an e-mail message.

You must pass the decrypted inner part of the message to this function, since Autocrypt-Gossip headers are only stored within the encrypted layer.

If you don't already have the decrypted inner part available to you, you probably want to use g_mime_message_get_autocrypt_gossip_headers instead.

Each header in the returned list will:

- have a valid address

- be of the type requested

- be complete

If no Autocrypt header is found for a recipient, no GMimeAutocryptHeader will be in the list associated with that e-mail address.

Note that the following types of Autocrypt headers will not be returned by this function:

- headers of an unrequested type

- headers that do not match an address in "From:"

- unparseable headers

- headers with unknown critical attributes

- duplicate valid headers for a given address

On error (e.g. if this version of GMime cannot handle the requested Autocrypt type, or if a parameter is missing or malformed), returns `NULL`

The returned Autocrypt headers will have their effective_date set to the earliest of either:

- the Date: header of the message or

- `now` (or the current time, if `now` is `NULL`)

#### Parameters

message | a GMimeMessage object. |
now | a GDateTime object, or `NULL` |
inner_part | a GMimeObject which is the cleartext part of the inner message |

#### Returns

a new GMimeAutocryptHeaderList object, or `NULL` on error.

[nullable][transfer full]

### g_mime_message_get_autocrypt_gossip_headers ()

    GMimeAutocryptHeaderList *
    g_mime_message_get_autocrypt_gossip_headers
                                   (GMimeMessage *message,
                                    GDateTime *now,
                                    GMimeDecryptFlags flags,
                                    const char *session_key,
                                    GError **err);

Creates a new GMimeAutocryptHeaderList of relevant headers of the given type based on the recipient(s) of an e-mail message.

Returns the same object as g_mime_message_get_autocrypt_gossip_headers_with_inner_part , but handles decryption and cleanup automatically.

`flags` and `session_key` are passed through to g_mime_multipart_encrypted_decrypt, as needed.

If the message is not actually an encrypted message, returns `NULL`: it should be ignored for purposes of evaluating gossip.

If decryption fails, returns `NULL`. In this case, an exception will be set on `err` to provide information about the decryption failure.

#### Parameters

message | a GMimeMessage object, which is expected to be encrypted. |
now | a GDateTime object, or `NULL` |
flags | a GMimeDecryptFlags, to be used during decryption |
session_key | session key to use or `NULL` |
err | a GError (can be `NULL`) |

#### Returns

a new GMimeAutocryptHeaderList object, or `NULL` on error.

[nullable][transfer full]

## Types and Values

### enum GMimeAddressType

An address type.

#### Members

GMIME_ADDRESS_TYPE_SENDER | Represents the addresses in the Sender header. |
GMIME_ADDRESS_TYPE_FROM | Represents the addresses in the From header. |
GMIME_ADDRESS_TYPE_REPLY_TO | Represents the addresses in the Reply-To header. |
GMIME_ADDRESS_TYPE_TO | Represents the recipients in the To header. |
GMIME_ADDRESS_TYPE_CC | Represents the recipients in the Cc header. |
GMIME_ADDRESS_TYPE_BCC | Represents the recipients in the Bcc header. |

### struct GMimeMessage

    struct GMimeMessage;

A MIME Message object.

#### Members