RustMailer Event Types Reference

This document outlines all event types emitted by the RustMailer system, including the data structures associated with each event.

`EventType` Enumeration

The EventType enum represents all possible events that RustMailer may emit during operation:

AccountFirstSyncCompleted: Triggered after the first successful account sync.
EmailAddedToFolder: Triggered when an email is added to a mailbox (new, copied, or moved).
EmailFlagsChanged: Triggered when flags (e.g., Seen, Replied) change for an email.
EmailSentSuccess: Triggered when an email is successfully sent via SMTP.
EmailSendingError: Triggered when email sending to SMTP fails (including retries).
EmailBounce: Triggered when a bounce is received for an email.
EmailFeedBackReport: Triggered when a feedback report is received.
EmailOpened: Triggered when a recipient opens an email.
EmailLinkClicked: Triggered when a recipient clicks a link in an email.
MailboxCreation: Triggered when one or more mailboxes are created.
MailboxDeletion: Triggered when one or more mailboxes are deleted.
UIDValidityChange: Triggered when UID validity of a mailbox changes.

Understanding Option<T> in JSON

In Rust, many fields are defined as Option<T>, meaning they are optional. These fields may or may not have a value.

When serialized to JSON:

If the value is Some(...), the field appears as usual.
If the value is None, it may either be missing from the JSON entirely or explicitly set to null.

This is normal and expected. If you're writing code or validating against these events, always account for optional fields possibly being absent.

Rust ↔ JSON Type Mapping

Rust Type	JSON Representation	Example
`String`	string	`"subject": "Hello"`
`u32`, `u64`	number	`"uid": 12345`
`bool`	boolean	`"inline": true`
`Vec<T>`	array	`"flags": ["Seen", "Flagged"]`
`Option<T>`	null or omitted entirely	`"subject": null` or missing
`HashMap<K, V>`	object	`"headers": {"X-Mailer": "x"}`

Common Data Structures

`Addr`

Represents an email address with an optional display name.

Field	Type	Description
name	`Option<String>`	Optional display name (e.g., "John Doe"). If `None`, no name.
address	`Option<String>`	Optional email address (e.g., "john.doe@example.com"). May be `None` if unavailable.

JSON Example for Addr:

{
  "name": "Jane Doe",
  "address": "jane.doe@example.com"
}

{
  "address": "info@example.com"
}

`MessageContent`

Represents the content of an email message, including optional plain text and HTML versions.

Field	Type	Description
plain	`Option<PlainText>`	Optional plain text version of the message.
html	`Option<String>`	Optional HTML version of the message.

JSON Example for MessageContent:

{
  "plain": {
    "content": "This is the plain text part of the email.",
    "truncated": false
  },
  "html": "<html><body><p>This is the <b>HTML</b> part of the email.</p></body></html>"
}

`PlainText`

Represents the plain text content of an email message.

Field	Type	Description
content	`String`	The plain text content itself.
truncated	`bool`	Whether the plain text was truncated (true if content is cut off).

JSON Example for PlainText:

{
  "content": "Hello, this is a plain text email.",
  "truncated": false
}

`Attachment`

Represents a single attachment file.

Field	Type	Description
filename	`Option<String>`	Name of the file.
inline	`bool`	Whether it is an inline attachment.
size	`usize`	Size in bytes.
file_type	`String`	MIME type of the file.

JSON Example for Attachment:

{
  "filename": "document.pdf",
  "inline": false,
  "size": 51200,
  "file_type": "application/pdf"
}

`RawEmailHeaders`

Represents raw headers extracted from an email.

Field	Type	Description
message_id	`Option<String>`	Optional unique message ID.
subject	`Option<String>`	Optional subject line.
from	`Option<String>`	Optional sender email address.
to	`Option<Vec<String>>`	Optional list of recipient addresses.
date	`Option<i64>`	Optional email date (milliseconds).

JSON Example for RawEmailHeaders:

{
  "message_id": "<abcdefg12345@example.com>",
  "subject": "Fwd: Your Latest Report",
  "from": "forwarder@example.com",
  "to": ["original.recipient@example.com"],
  "date": 1678886400000
}

`DeliveryStatus`

Details about the delivery outcome of an email, typically for bounces.

Field	Type	Description
recipient	`Option<String>`	Recipient address for which delivery failed.
action	`Option<String>`	Action taken by server (e.g., "failed", "delayed").
status	`Option<String>`	Status code or description of delivery outcome.
error_source	`Option<String>`	Source of error (e.g., "smtp", "dns").
diagnostic_code	`Option<String>`	Diagnostic details for failure.
remote_mta	`Option<String>`	Remote Mail Transfer Agent involved.
reporting_mta	`Option<String>`	MTA that generated the bounce report.
received_from_mta	`Option<String>`	MTA from which email was received.
postfix_queue_id	`Option<String>`	Postfix queue ID related to the email.
arrival_date	`Option<String>`	Date/time email arrived at MTA (string format).
original_message_id	`Option<String>`	Original email's message ID.
postfix_sender	`Option<String>`	Sender address used by Postfix.

JSON Example for DeliveryStatus:

{
  "recipient": "nonexistent@example.com",
  "action": "failed",
  "status": "5.1.1",
  "error_source": "smtp",
  "diagnostic_code": "smtp; 550 5.1.1 <nonexistent@example.com>: Recipient address rejected: User unknown in local recipient table",
  "remote_mta": "mail.remoteserver.com",
  "reporting_mta": "mail.reportingserver.com",
  "original_message_id": "<unique_msg_id_123@sender.com>"
}

`FeedbackReport`

Represents a feedback report (e.g., abuse, spam reports).

Field	Type	Description
feedback_type	`Option<String>`	Type of feedback (e.g., "abuse", "spam").
version	`Option<String>`	Version of feedback report format.
user_agent	`Option<String>`	User agent of reporting client/system.
original_mail_from	`Option<String>`	Original sender address from email envelope.
original_rcpt_to	`Option<String>`	Original recipient address from envelope.
original_envelope_id	`Option<String>`	Original envelope ID.
received_date	`Option<String>`	Date/time feedback was received (string).
reported_domain	`Option<String>`	Domain reported in feedback.
reported_uri	`Option<String>`	URI reported (e.g., unsubscribe link).
reporting_mta	`Option<String>`	MTA that generated the feedback report.
source_ip	`Option<String>`	IP address of feedback source.
source_port	`Option<String>`	Port used by feedback source.
spf_dns	`Option<String>`	DNS record used for SPF validation.
delivery_result	`Option<String>`	Result of delivery attempt related to feedback.
authentication_results	`Option<String>`	Authentication results (e.g., DKIM, SPF).
auth_failure	`Option<String>`	Details of authentication failure.
arrival_date	`Option<String>`	Arrival date/time of email (string).

JSON Example for FeedbackReport:

{
  "feedback_type": "abuse",
  "version": "1.0",
  "user_agent": "SomeISP-FBL-Processor/1.0",
  "original_mail_from": "sender@example.com",
  "original_rcpt_to": "complainer@example.com",
  "reporting_mta": "fbl.isp.com",
  "source_ip": "192.0.2.1",
  "reported_uri": "http://example.com/unsubscribe",
  "authentication_results": "spf=pass (sender@example.com) dkim=pass (header.d=example.com)"
}

Event Types and Their Structures

`AccountFirstSyncCompleted`

Triggered after the first successful account sync. Uses the same structure as AccountChange.

Field	Type	Description
account_id	`u64`	Account ID.
account_email	`String`	Email address.

JSON Example for AccountFirstSyncCompleted:

{
  "account_id": 98765,
  "account_email": "newuser@example.com"
}

`EmailAddedToFolder`

Triggered when an email is added to a mailbox (new, copied, or moved).

Field	Type	Description
account_id	`u64`	Unique account ID.
account_email	`String`	Account email address.
mailbox_name	`String`	Name of the mailbox/folder.
uid	`u32`	IMAP UID of the email.
internal_date	`Option<i64>`	Server internal date (ms).
date	`Option<i64>`	Date from email header (ms).
size	`u32`	Size of the email (bytes).
flags	`Vec<String>`	List of flags (e.g., Seen).
cc	`Option<Vec<Addr>>`	Carbon copy recipients.
bcc	`Option<Vec<Addr>>`	Blind carbon copy recipients.
from	`Option<Addr>`	Sender address.
in_reply_to	`Option<String>`	Reply-to message ID.
sender	`Option<Addr>`	Sender field from header.
message_id	`Option<String>`	Email message ID.
subject	`Option<String>`	Subject line.
message	`MessageContent`	Email content and metadata.
thread_name	`Option<String>`	Optional thread name.
reply_to	`Option<Vec<Addr>>`	List of reply-to addresses.
to	`Option<Vec<Addr>>`	Primary recipients.
attachments	`Option<Vec<Attachment>>`	Email attachments.

JSON Example for EmailAddedToFolder:

{
  "account_id": 12345,
  "account_email": "user@example.com",
  "mailbox_name": "Inbox",
  "uid": 67890,
  "internal_date": 1678886400000,
  "date": 1678886390000,
  "size": 2548,
  "flags": ["Seen", "Answered"],
  "from": {
    "name": "Sender Name",
    "address": "sender@example.com"
  },
  "to": [
    {
      "name": "Recipient One",
      "address": "recipient1@example.com"
    },
    {
      "address": "recipient2@example.com"
    }
  ],
  "subject": "Meeting Reminder",
  "message_id": "<abcde12345@example.com>",
  "message": {
    "plain": {
      "content": "Hi team, just a reminder about our meeting tomorrow at 10 AM.",
      "truncated": false
    },
    "html": "<html><body><p>Hi team, just a reminder about our meeting tomorrow at <b>10 AM</b>.</p></body></html>"
  },
  "attachments": [
    {
      "filename": "agenda.pdf",
      "inline": false,
      "size": 102400,
      "file_type": "application/pdf"
    }
  ]
}

`EmailFlagsChanged`

Triggered when flags are changed for an email.

Field	Type	Description
account_id	`u64`	Account ID.
account_email	`String`	Account email address.
mailbox_name	`String`	Affected mailbox.
uid	`u32`	UID of the email.
from	`Option<Addr>`	Sender.
to	`Option<Vec<Addr>>`	Recipients.
message_id	`Option<String>`	Email message ID.
subject	`Option<String>`	Email subject.
internal_date	`Option<i64>`	Internal date (ms).
date	`Option<i64>`	Email date (ms).
flags_added	`Vec<String>`	Flags added.
flags_removed	`Vec<String>`	Flags removed.

JSON Example for EmailFlagsChanged:

{
  "account_id": 12345,
  "account_email": "user@example.com",
  "mailbox_name": "Inbox",
  "uid": 67890,
  "from": {
    "address": "sender@example.com"
  },
  "to": [
    {
      "address": "recipient@example.com"
    }
  ],
  "subject": "Important Update",
  "message_id": "<abcde12345@example.com>",
  "internal_date": 1678886400000,
  "date": 1678886390000,
  "flags_added": ["Seen"],
  "flags_removed": []
}

`EmailSentSuccess`

Triggered when an email is successfully sent.

Field	Type	Description
account_id	`u64`	Account ID.
account_email	`String`	Account email address.
from	`String`	Sender address.
to	`Vec<String>`	Recipient list.
subject	`Option<String>`	Email subject.
message_id	`String`	Message ID.

JSON Example for EmailSentSuccess:

{
  "account_id": 12345,
  "account_email": "user@example.com",
  "from": "sender@example.com",
  "to": ["recipient@example.com", "cc@example.com"],
  "subject": "Your Order Confirmation",
  "message_id": "<sent_msg_id_789@example.com>"
}

`EmailSendingError`

Triggered when email sending fails (on each retry).

Field	Type	Description
account_id	`u64`	Account ID.
account_email	`String`	Account email address.
from	`String`	Sender address.
to	`Vec<String>`	Recipient list.
subject	`Option<String>`	Subject.
message_id	`String`	Message ID.
error_msg	`Option<String>`	Error message.
retry_count	`Option<usize>`	Retry attempts.
scheduled_at	`Option<i64>`	Scheduled time (ms).
task_id	`u64`	Sending task ID.
max_retries	`Option<u32>`	Max retry limit.

JSON Example for EmailSendingError:

{
  "account_id": 12345,
  "account_email": "user@example.com",
  "from": "sender@example.com",
  "to": ["invalid@example.com"],
  "subject": "Test Email",
  "message_id": "<failed_msg_id_101@example.com>",
  "error_msg": "SMTP 550 Recipient not found",
  "retry_count": 1,
  "scheduled_at": 1678886500000,
  "task_id": 123456789,
  "max_retries": 3
}

`EmailBounce`

Triggered when a bounce notification is received.

Field	Type	Description
account_id	`u64`	Account ID.
account_email	`String`	Email address.
mailbox_name	`String`	Affected folder.
uid	`u32`	Email UID.
internal_date	`Option<i64>`	Internal date.
date	`Option<i64>`	Email date.
from	`Option<Addr>`	Sender.
subject	`Option<String>`	Subject.
to	`Option<Vec<Addr>>`	Recipients.
original_headers	`Option<RawEmailHeaders>`	Original headers.
delivery_status	`Option<DeliveryStatus>`	Bounce details.

JSON Example for EmailBounce:

{
  "account_id": 12345,
  "account_email": "user@example.com",
  "mailbox_name": "Inbox",
  "uid": 98765,
  "internal_date": 1678886400000,
  "date": 1678886390000,
  "from": {
    "address": "MAILER-DAEMON@example.com"
  },
  "subject": "Undelivered Mail Returned to Sender",
  "to": [
    {
      "address": "original-recipient@example.com"
    }
  ],
  "original_headers": {
    "message_id": "<original_message_id_abc@sender.com>",
    "subject": "Your Newsletter",
    "from": "newsletter@example.com",
    "to": ["original-recipient@example.com"]
  },
  "delivery_status": {
    "recipient": "original-recipient@example.com",
    "action": "failed",
    "status": "5.1.1",
    "diagnostic_code": "smtp; 550 5.1.1 User unknown"
  }
}

`EmailFeedBackReport`

Triggered when a feedback loop report is received.

Field	Type	Description
account_id	`u64`	Account ID.
account_email	`String`	Email address.
mailbox_name	`String`	Folder containing the message.
uid	`u32`	Email UID.
internal_date	`Option<i64>`	Internal date.
date	`Option<i64>`	Email date.
from	`Option<Addr>`	Sender.
subject	`Option<String>`	Subject.
to	`Option<Vec<Addr>>`	Recipients.
original_headers	`Option<RawEmailHeaders>`	Original headers.
feedback_report	`Option<FeedbackReport>`	Report details.

JSON Example for EmailFeedBackReport:

{
  "account_id": 12345,
  "account_email": "user@example.com",
  "mailbox_name": "Inbox",
  "uid": 98765,
  "internal_date": 1678886400000,
  "date": 1678886390000,
  "from": {
    "address": "abuse@example.com"
  },
  "subject": "Spam Report for your message",
  "to": [
    {
      "address": "feedback-recipient@example.com"
    }
  ],
  "original_headers": {
    "message_id": "<original_message_id_xyz@sender.com>",
    "subject": "Promotional Offer",
    "from": "marketing@example.com",
    "to": ["feedback-recipient@example.com"]
  },
  "feedback_report": {
    "feedback_type": "spam",
    "version": "1.0",
    "original_mail_from": "marketing@example.com",
    "original_rcpt_to": "feedback-recipient@example.com",
    "reporting_mta": "fbl.example.net",
    "source_ip": "203.0.113.45"
  }
}

`EmailOpened`

Triggered when an email is opened by a recipient.

Field	Type	Description
campaign_id	`String`	Campaign identifier.
recipient	`String`	Recipient email.
message_id	`String`	Email message ID.
user_agent	`String`	User agent of client.
remote_ip	`Option<String>`	Client IP address.

JSON Example for EmailOpened:

{
  "campaign_id": "promo_july_2025",
  "recipient": "recipient@example.com",
  "message_id": "<tracking_msg_id_123@campaign.com>",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
  "remote_ip": "203.0.113.10"
}

`EmailLinkClicked`

Triggered when a recipient clicks a link.

Field	Type	Description
campaign_id	`String`	Campaign ID.
recipient	`String`	Recipient email.
message_id	`String`	Message ID.
url	`String`	Clicked URL.
remote_ip	`Option<String>`	IP address.
user_agent	`String`	User agent.

JSON Example for EmailLinkClicked:

{
  "campaign_id": "promo_july_2025",
  "recipient": "recipient@example.com",
  "message_id": "<tracking_msg_id_123@campaign.com>",
  "url": "https://example.com/promo/summer-sale",
  "remote_ip": "203.0.113.10",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36"
}

`MailboxCreation`

Triggered when mailboxes are created. Uses the same structure as MailboxChange.

Field	Type	Description
account_id	`u64`	Account ID.
account_email	`String`	Account email address.
mailbox_names	`Vec<String>`	Affected mailbox names.

JSON Example for MailboxCreation:

{
  "account_id": 12345,
  "account_email": "user@example.com",
  "mailbox_names": ["New Folder", "Archives/2025"]
}

`MailboxDeletion`

Triggered when mailboxes are deleted. Uses the same structure as MailboxChange.

Field	Type	Description
account_id	`u64`	Account ID.
account_email	`String`	Account email address.
mailbox_names	`Vec<String>`	Affected mailbox names.

JSON Example for MailboxDeletion:

{
  "account_id": 12345,
  "account_email": "user@example.com",
  "mailbox_names": ["Old Drafts", "Temporary"]
}

`UIDValidityChange`

Triggered when UID validity of a mailbox changes. Uses the same structure as MailboxChange.

Field	Type	Description
account_id	`u64`	Account ID.
account_email	`String`	Account email address.
mailbox_names	`Vec<String>`	Affected mailbox names.

JSON Example for UIDValidityChange:

{
  "account_id": 12345,
  "account_email": "user@example.com",
  "mailbox_names": ["Inbox"]
}

Sure, here's the tip you requested:

Incremental Synchronization and Event Triggers

Most email and mailbox-related events are detected during incremental synchronization with the mail server. For example, if your sync interval is 20 seconds, new emails arriving, bounce notifications, and changes to email flags will typically be detected and trigger their respective events within that 20-second window. This ensures timely updates without constant server polling.

EventType Enumeration​

Rust ↔ JSON Type Mapping​

Common Data Structures​

Addr​

MessageContent​

PlainText​

Attachment​

RawEmailHeaders​

DeliveryStatus​

FeedbackReport​

Event Types and Their Structures​

AccountFirstSyncCompleted​

EmailAddedToFolder​

EmailFlagsChanged​

EmailSentSuccess​

EmailSendingError​

EmailBounce​

EmailFeedBackReport​

EmailOpened​

EmailLinkClicked​

MailboxCreation​

MailboxDeletion​

UIDValidityChange​