![]() |
GPAL - Generally Positive Automation Library v1.0
GPAL The Fluent Automation LIbrary
|
Provides a fluent API for configuring, sending, and receiving email via SMTP, IMAP, and POP. Supports specifying server connection settings, envelope details (from/to/cc/bcc, subject, body, attachments), sending mail through SMTP, retrieving messages from an IMAP inbox, and persisting/loading mail settings to/from a GPALFile. More...
Public Member Functions | |
| IGPALMail | ToGPALObject () |
| Returns this instance cast to IGPALMail, allowing the fluent chain to be converted back to the root mail interface. | |
| IAllowEmailServerSettingsAndName | WithIMAPServerName (string serverName) |
| Sets the IMAP server hostname used for receiving mail, and forgets any POP server, since Receive reads from one server or the other. | |
| IAllowEmailServerSettingsAndName | WithPOPServerName (string serverName) |
| Sets the POP server hostname used for receiving mail, and forgets any IMAP server, since Receive reads from one server or the other. | |
| IAllowEmailServerSettingsAndName | WithSMTPServerName (string serverName) |
| Sets the SMTP server hostname used for sending mail. | |
| IAllowEmailServerSettingsAndName | WithIMAPPortNum (int portNum=993) |
| Sets the port number used to connect to the IMAP server. | |
| IAllowEmailServerSettingsAndName | WithPOPPortNum (int portNum=110) |
| Sets the port number used to connect to the POP server. | |
| IAllowEmailServerSettingsAndName | WithSMTPPortNum (int portNum=465) |
| Sets the port number used to connect to the SMTP server. | |
| IAllowEmailServerSettingsAndName | WithCredentials (ICredentials credentials) |
| The credential to authenticate with, from wherever GPAL got it: a vault, a file, or set by hand. Its username and password win over WithUserName and WithPassword. | |
| IAllowEmailServerSettingsAndName | WithUserName (string userName) |
| Sets the username used to authenticate with the mail server(s). | |
| IAllowEmailServerSettingsAndName | WithPassword (string password) |
| Sets the password used to authenticate with the mail server(s). | |
| IAllowNameEnvelopeAndActions | WithFromEmailAddress (string mailAddress) |
| IAllowNameEnvelopeAndActions | WithToEmailAddress (string mailAddress) |
| Adds one or more "To" recipients, parsed from a single string that may contain multiple addresses delimited by commas, semicolons, or pipes. | |
| IAllowNameEnvelopeAndActions | WithCcEmailAddress (string mailAddress) |
| Adds one or more "Cc" recipients, parsed from a single string that may contain multiple addresses delimited by commas, semicolons, or pipes. | |
| IAllowNameEnvelopeAndActions | WithBccEmailAddress (string mailAddress) |
| Adds one or more "Bcc" recipients, parsed from a single string that may contain multiple addresses delimited by commas, semicolons, or pipes. | |
| IAllowNameEnvelopeAndActions | WithToEmailAddress (string[] emailParts) |
| Adds one or more "To" recipients from an array of email address strings. | |
| IAllowNameEnvelopeAndActions | WithCcEmailAddress (string[] emailParts) |
| Adds one or more "Cc" recipients from an array of email address strings. | |
| IAllowNameEnvelopeAndActions | WithBccEmailAddress (string[] emailParts) |
| Adds one or more "Bcc" recipients from an array of email address strings. | |
| IAllowEmailEnvelopeAndActions | WithAttachment (GPALFile attachmentFile) |
| Adds the file(s) referenced by the given GPALFile as email attachments. Each filename in GPALFile.Filenames is treated as a (possibly wildcarded) path; matching files in the resolved directory are added to the attachment list. Errors resolving or adding individual files are logged via GPAL.PublishSimpleEvent rather than thrown, allowing the remaining attachments to still be processed. | |
| IAllowEmailEnvelopeAndActions | WithBody (string body) |
| Sets the message body, automatically detecting whether it is HTML or plain text via IsHtml(string) and storing it as GPALMailSettings.BodyHTML or GPALMailSettings.BodyText accordingly. | |
| IAllowEmailEnvelopeAndActions | WithSubject (string subject) |
| Sets the subject line of the message. | |
| IAllowEmailEnvelopeAndActions | WithName (string name) |
| Sets the display name on the address added just before this call, whether that was the from, a to, a cc or a bcc. Warns and does nothing when no address has been added yet. | |
| IAllowEmailEnvelopeAndActions | Send () |
| Builds the message from the configured envelope (from/to/cc/bcc, subject, body, attachments) and sends it via SMTP using GPALMailSettings.SMTPServerName and GPALMailSettings.SMTPPortNum. If the initial connection fails (typically due to a certificate issue), retries with certificate validation disabled and TLS 1.1/1.2 explicitly enabled. | |
| IAllowEmailEnvelopeAndActions | Receive () |
| Connects to the configured IMAP server, authenticates with GPALMailSettings.UserName and GPALMailSettings.Password, opens the inbox read-only, and copies every message into GPALMailSettings.ReceivedEmails as a ReceivedEmail (subject, from, and text body). | |
| IAllowEmailEnvelopeAndActions | Receive (out List< ReceivedEmail > receivedEmails) |
| Reads the mail as Receive does and hands the messages over in one call. | |
| IAllowEmailEnvelopeAndActions | WithUnreadOnly (bool unreadOnly) |
| Limits Receive() to the messages the server still has as unread. Off by default, so a Receive with nothing said fetches every message as it always has. | |
| IAllowEmailEnvelopeAndActions | WithMaxMessages (int maxMessages) |
| Caps how many messages one Receive() fetches, taking the newest first. Every message by default, which on a mailbox of any size is a great deal of downloading. | |
| IAllowEmailEnvelopeAndActions | MarkAllAsRead () |
| Marks every message Receive() collected as read on the server, in one connection, so the next Receive set to unread only leaves them behind. Call it once the workflow has finished with them rather than before. IMAP only. | |
| IAllowEmailEnvelopeAndActions | DeleteAll () |
| Deletes every message Receive() collected from the server, flagging and expunging them in one connection. Anything not received is untouched, so this empties what the workflow read rather than the mailbox. IMAP only. | |
| IAllowEmailEnvelopeAndActions | SaveTo (GPALFile directory) |
| Writes every attachment on every message Receive collected into the given directory, creating it when it is not there. Use ReceivedEmail.SaveTo(GPALFile) for one message's. | |
| IAllowEmailEnvelopeAndActions | Clear () |
| Resets the email envelope to a blank state: clears all recipient lists, subject, body text, attachments, and any received emails. The from address and the server connection settings (host/port/credentials) are left unchanged. | |
| IAllowEmailEnvelopeAndActions | LoadSettings (GPALFile mailSettingsFile=null) |
| Loads this instance's GPALMailSettings from the given GPALFile via GPAL.Converter, replacing the current server connection and envelope settings. | |
| IAllowEmailEnvelopeAndActions | SaveSettings (GPALFile mailSettingsFile=null) |
| Saves this instance's GPALMailSettings (server connection and envelope settings) to the given GPALFile via GPAL.Converter. | |
Static Public Member Functions | |
| static List< MailboxAddress > | ParseEmailAddresses (string input) |
| Splits a single string containing one or more email addresses delimited by commas, semicolons, or pipes, and parses each into a MailboxAddress. | |
Properties | |
| string | SMTPServerName [get] |
| The SMTP server mail is sent through, as set by WithSMTPServerName or read from a settings file. | |
| int | SMTPPortNum [get] |
| The port used to reach SMTPServerName. | |
| string | IMAPServerName [get] |
| The IMAP server mail is read from, null when a POP server is the one named. | |
| int | IMAPPortNum [get] |
| The port used to reach IMAPServerName. | |
| string | POPServerName [get] |
| The POP server mail is read from, null when an IMAP server is the one named. | |
| int | POPPortNum [get] |
| The port used to reach POPServerName. | |
| string | FromAddress [get] |
| The address messages are sent from, as text, with the display name when there is one. | |
Provides a fluent API for configuring, sending, and receiving email via SMTP, IMAP, and POP. Supports specifying server connection settings, envelope details (from/to/cc/bcc, subject, body, attachments), sending mail through SMTP, retrieving messages from an IMAP inbox, and persisting/loading mail settings to/from a GPALFile.
Definition at line 54 of file GPALMail.cs.
| IAllowEmailEnvelopeAndActions GenerallyPositive.GPALMail.Clear | ( | ) |
Resets the email envelope to a blank state: clears all recipient lists, subject, body text, attachments, and any received emails. The from address and the server connection settings (host/port/credentials) are left unchanged.
Implements GenerallyPositive.IAllowEmailActions.
Definition at line 712 of file GPALMail.cs.
| IAllowEmailEnvelopeAndActions GenerallyPositive.GPALMail.DeleteAll | ( | ) |
Deletes every message Receive() collected from the server, flagging and expunging them in one connection. Anything not received is untouched, so this empties what the workflow read rather than the mailbox. IMAP only.
Implements GenerallyPositive.IAllowEmailActions.
Definition at line 624 of file GPALMail.cs.
| IAllowEmailEnvelopeAndActions GenerallyPositive.GPALMail.LoadSettings | ( | GPALFile | mailSettingsFile = null | ) |
Loads this instance's GPALMailSettings from the given GPALFile via GPAL.Converter, replacing the current server connection and envelope settings.
| mailSettingsFile | The file to load mail settings from. |
Implements GenerallyPositive.IAllowEmailActions.
Definition at line 731 of file GPALMail.cs.
| IAllowEmailEnvelopeAndActions GenerallyPositive.GPALMail.MarkAllAsRead | ( | ) |
Marks every message Receive() collected as read on the server, in one connection, so the next Receive set to unread only leaves them behind. Call it once the workflow has finished with them rather than before. IMAP only.
Implements GenerallyPositive.IAllowEmailActions.
Definition at line 612 of file GPALMail.cs.
|
static |
Splits a single string containing one or more email addresses delimited by commas, semicolons, or pipes, and parses each into a MailboxAddress.
| input | A delimited string of one or more email addresses. |
Definition at line 764 of file GPALMail.cs.
| IAllowEmailEnvelopeAndActions GenerallyPositive.GPALMail.Receive | ( | ) |
Connects to the configured IMAP server, authenticates with GPALMailSettings.UserName and GPALMailSettings.Password, opens the inbox read-only, and copies every message into GPALMailSettings.ReceivedEmails as a ReceivedEmail (subject, from, and text body).
Implements GenerallyPositive.IAllowEmailActions.
Definition at line 508 of file GPALMail.cs.
| IAllowEmailEnvelopeAndActions GenerallyPositive.GPALMail.Receive | ( | out List< ReceivedEmail > | receivedEmails | ) |
Reads the mail as Receive does and hands the messages over in one call.
| receivedEmails | Receives the messages, empty when nothing was fetched |
Implements GenerallyPositive.IAllowEmailActions.
Definition at line 527 of file GPALMail.cs.
| IAllowEmailEnvelopeAndActions GenerallyPositive.GPALMail.SaveSettings | ( | GPALFile | mailSettingsFile = null | ) |
Saves this instance's GPALMailSettings (server connection and envelope settings) to the given GPALFile via GPAL.Converter.
| mailSettingsFile | The file to save mail settings to. |
Implements GenerallyPositive.IAllowEmailActions.
Definition at line 751 of file GPALMail.cs.
| IAllowEmailEnvelopeAndActions GenerallyPositive.GPALMail.SaveTo | ( | GPALFile | directory | ) |
Writes every attachment on every message Receive collected into the given directory, creating it when it is not there. Use ReceivedEmail.SaveTo(GPALFile) for one message's.
| directory | The directory to write the attachments into |
Implements GenerallyPositive.IAllowEmailActions.
Definition at line 694 of file GPALMail.cs.
| IAllowEmailEnvelopeAndActions GenerallyPositive.GPALMail.Send | ( | ) |
Builds the message from the configured envelope (from/to/cc/bcc, subject, body, attachments) and sends it via SMTP using GPALMailSettings.SMTPServerName and GPALMailSettings.SMTPPortNum. If the initial connection fails (typically due to a certificate issue), retries with certificate validation disabled and TLS 1.1/1.2 explicitly enabled.
Implements GenerallyPositive.IAllowEmailActions.
Definition at line 436 of file GPALMail.cs.
| IGPALMail GenerallyPositive.GPALMail.ToGPALObject | ( | ) |
Returns this instance cast to IGPALMail, allowing the fluent chain to be converted back to the root mail interface.
Implements GenerallyPositive.IAllowToGPALObject< TResult >.
Definition at line 92 of file GPALMail.cs.
| IAllowEmailEnvelopeAndActions GenerallyPositive.GPALMail.WithAttachment | ( | GPALFile | attachmentFile | ) |
Adds the file(s) referenced by the given GPALFile as email attachments. Each filename in GPALFile.Filenames is treated as a (possibly wildcarded) path; matching files in the resolved directory are added to the attachment list. Errors resolving or adding individual files are logged via GPAL.PublishSimpleEvent rather than thrown, allowing the remaining attachments to still be processed.
| attachmentFile | The GPALFile describing the file(s) to attach. |
Implements GenerallyPositive.IAllowEmailEnvelope.
Definition at line 344 of file GPALMail.cs.
| IAllowNameEnvelopeAndActions GenerallyPositive.GPALMail.WithBccEmailAddress | ( | string | mailAddress | ) |
Adds one or more "Bcc" recipients, parsed from a single string that may contain multiple addresses delimited by commas, semicolons, or pipes.
| mailAddress | A delimited string of one or more recipient email addresses. |
Implements GenerallyPositive.IAllowEmailEnvelope.
Definition at line 282 of file GPALMail.cs.
| IAllowNameEnvelopeAndActions GenerallyPositive.GPALMail.WithBccEmailAddress | ( | string[] | emailParts | ) |
Adds one or more "Bcc" recipients from an array of email address strings.
| emailParts | An array of recipient email addresses. |
Implements GenerallyPositive.IAllowEmailEnvelope.
Definition at line 326 of file GPALMail.cs.
| IAllowEmailEnvelopeAndActions GenerallyPositive.GPALMail.WithBody | ( | string | body | ) |
Sets the message body, automatically detecting whether it is HTML or plain text via IsHtml(string) and storing it as GPALMailSettings.BodyHTML or GPALMailSettings.BodyText accordingly.
| body | The message body, as plain text or HTML markup. |
Implements GenerallyPositive.IAllowEmailEnvelope.
Definition at line 380 of file GPALMail.cs.
| IAllowNameEnvelopeAndActions GenerallyPositive.GPALMail.WithCcEmailAddress | ( | string | mailAddress | ) |
Adds one or more "Cc" recipients, parsed from a single string that may contain multiple addresses delimited by commas, semicolons, or pipes.
| mailAddress | A delimited string of one or more recipient email addresses. |
Implements GenerallyPositive.IAllowEmailEnvelope.
Definition at line 266 of file GPALMail.cs.
| IAllowNameEnvelopeAndActions GenerallyPositive.GPALMail.WithCcEmailAddress | ( | string[] | emailParts | ) |
Adds one or more "Cc" recipients from an array of email address strings.
| emailParts | An array of recipient email addresses. |
Implements GenerallyPositive.IAllowEmailEnvelope.
Definition at line 311 of file GPALMail.cs.
| IAllowEmailServerSettingsAndName GenerallyPositive.GPALMail.WithCredentials | ( | ICredentials | credentials | ) |
The credential to authenticate with, from wherever GPAL got it: a vault, a file, or set by hand. Its username and password win over WithUserName and WithPassword.
| credentials | The credential to authenticate with |
Implements GenerallyPositive.IAllowEmailServerSettings.
Definition at line 169 of file GPALMail.cs.
| IAllowNameEnvelopeAndActions GenerallyPositive.GPALMail.WithFromEmailAddress | ( | string | mailAddress | ) |
Implements GenerallyPositive.IAllowEmailEnvelope.
Definition at line 238 of file GPALMail.cs.
| IAllowEmailServerSettingsAndName GenerallyPositive.GPALMail.WithIMAPPortNum | ( | int | portNum = 993 | ) |
Sets the port number used to connect to the IMAP server.
| portNum | The IMAP port number. Defaults to 993 (IMAP over SSL/TLS). |
Implements GenerallyPositive.IAllowEmailServerSettings.
Definition at line 138 of file GPALMail.cs.
| IAllowEmailServerSettingsAndName GenerallyPositive.GPALMail.WithIMAPServerName | ( | string | serverName | ) |
Sets the IMAP server hostname used for receiving mail, and forgets any POP server, since Receive reads from one server or the other.
| serverName | The IMAP server hostname or address. |
Implements GenerallyPositive.IAllowEmailServerSettings.
Definition at line 102 of file GPALMail.cs.
| IAllowEmailEnvelopeAndActions GenerallyPositive.GPALMail.WithMaxMessages | ( | int | maxMessages | ) |
Caps how many messages one Receive() fetches, taking the newest first. Every message by default, which on a mailbox of any size is a great deal of downloading.
| maxMessages | The most messages to fetch. |
Implements GenerallyPositive.IAllowEmailReceiveOptions.
Definition at line 556 of file GPALMail.cs.
| IAllowEmailEnvelopeAndActions GenerallyPositive.GPALMail.WithName | ( | string | name | ) |
Sets the display name on the address added just before this call, whether that was the from, a to, a cc or a bcc. Warns and does nothing when no address has been added yet.
| name | The display name to show alongside that address. |
Implements GenerallyPositive.IAllowName.
Definition at line 406 of file GPALMail.cs.
| IAllowEmailServerSettingsAndName GenerallyPositive.GPALMail.WithPassword | ( | string | password | ) |
Sets the password used to authenticate with the mail server(s).
| password | The account password. |
Implements GenerallyPositive.IAllowEmailServerSettings.
Definition at line 224 of file GPALMail.cs.
| IAllowEmailServerSettingsAndName GenerallyPositive.GPALMail.WithPOPPortNum | ( | int | portNum = 110 | ) |
Sets the port number used to connect to the POP server.
| portNum | The POP port number. Defaults to 110 (plain POP3). |
Implements GenerallyPositive.IAllowEmailServerSettings.
Definition at line 148 of file GPALMail.cs.
| IAllowEmailServerSettingsAndName GenerallyPositive.GPALMail.WithPOPServerName | ( | string | serverName | ) |
Sets the POP server hostname used for receiving mail, and forgets any IMAP server, since Receive reads from one server or the other.
| serverName | The POP server hostname or address. |
Implements GenerallyPositive.IAllowEmailServerSettings.
Definition at line 115 of file GPALMail.cs.
| IAllowEmailServerSettingsAndName GenerallyPositive.GPALMail.WithSMTPPortNum | ( | int | portNum = 465 | ) |
Sets the port number used to connect to the SMTP server.
| portNum | The SMTP port number. Defaults to 465 (SMTP over SSL/TLS). |
Implements GenerallyPositive.IAllowEmailServerSettings.
Definition at line 158 of file GPALMail.cs.
| IAllowEmailServerSettingsAndName GenerallyPositive.GPALMail.WithSMTPServerName | ( | string | serverName | ) |
Sets the SMTP server hostname used for sending mail.
| serverName | The SMTP server hostname or address. |
Implements GenerallyPositive.IAllowEmailServerSettings.
Definition at line 127 of file GPALMail.cs.
| IAllowEmailEnvelopeAndActions GenerallyPositive.GPALMail.WithSubject | ( | string | subject | ) |
Sets the subject line of the message.
| subject | The subject text. |
Implements GenerallyPositive.IAllowEmailEnvelope.
Definition at line 394 of file GPALMail.cs.
| IAllowNameEnvelopeAndActions GenerallyPositive.GPALMail.WithToEmailAddress | ( | string | mailAddress | ) |
Adds one or more "To" recipients, parsed from a single string that may contain multiple addresses delimited by commas, semicolons, or pipes.
| mailAddress | A delimited string of one or more recipient email addresses. |
Implements GenerallyPositive.IAllowEmailEnvelope.
Definition at line 250 of file GPALMail.cs.
| IAllowNameEnvelopeAndActions GenerallyPositive.GPALMail.WithToEmailAddress | ( | string[] | emailParts | ) |
Adds one or more "To" recipients from an array of email address strings.
| emailParts | An array of recipient email addresses. |
Implements GenerallyPositive.IAllowEmailEnvelope.
Definition at line 296 of file GPALMail.cs.
| IAllowEmailEnvelopeAndActions GenerallyPositive.GPALMail.WithUnreadOnly | ( | bool | unreadOnly | ) |
Limits Receive() to the messages the server still has as unread. Off by default, so a Receive with nothing said fetches every message as it always has.
| unreadOnly | True to fetch only unread messages. |
Implements GenerallyPositive.IAllowEmailReceiveOptions.
Definition at line 544 of file GPALMail.cs.
| IAllowEmailServerSettingsAndName GenerallyPositive.GPALMail.WithUserName | ( | string | userName | ) |
Sets the username used to authenticate with the mail server(s).
| userName | The account username. |
Implements GenerallyPositive.IAllowEmailServerSettings.
Definition at line 214 of file GPALMail.cs.
|
get |
The address messages are sent from, as text, with the display name when there is one.
Implements GenerallyPositive.IGPALMail.
Definition at line 190 of file GPALMail.cs.
|
get |
The port used to reach IMAPServerName.
Implements GenerallyPositive.IGPALMail.
Definition at line 184 of file GPALMail.cs.
|
get |
The IMAP server mail is read from, null when a POP server is the one named.
Implements GenerallyPositive.IGPALMail.
Definition at line 182 of file GPALMail.cs.
|
get |
The port used to reach POPServerName.
Implements GenerallyPositive.IGPALMail.
Definition at line 188 of file GPALMail.cs.
|
get |
The POP server mail is read from, null when an IMAP server is the one named.
Implements GenerallyPositive.IGPALMail.
Definition at line 186 of file GPALMail.cs.
|
get |
The port used to reach SMTPServerName.
Implements GenerallyPositive.IGPALMail.
Definition at line 180 of file GPALMail.cs.
|
get |
The SMTP server mail is sent through, as set by WithSMTPServerName or read from a settings file.
Implements GenerallyPositive.IGPALMail.
Definition at line 178 of file GPALMail.cs.