OpenXchangeClient.Api.Mail (open_xchange_client v0.10.1)
API calls for all endpoints tagged Mail
.
Link to this section Summary
Functions
Auto saves an e-mail as draft.
Clears the content of mail folders.
Copies a mail to another folder.
Deletes mails.
Examines a specifed mail folder and provides its basic status information
Forwards a mail. Returns the data for the message that shall be forwarded.
Gets all mails.
Gets multiple mail attachments as a ZIP file.
Gets a mail.
Gets a mail attachment.
Gets all mail conversations.
Gets the mail count.
Gets the message headers as plain text.
Gets a list of mails.
Gets the complete message source as plain text.
Gets updated mails. Provides a list of updated mails. Attention: This does not work for IMAP mail accounts. In case of imap accounts an empty list is returned.
Gets multiple mails as a ZIP file.
Gets all mail thread references.
Import of mails as MIME data block (RFC822). This request can be used to store a single or a lot of mails in the OX mail storage backend. This action should be used instead of /mail?action=new because it is faster and tolerant to 8-bit encoded emails. To import multiple mails add further form-data fields.
Marks all mails of a folder as seen.
Stores a mail attachment to the drive.
Requests a delivery receipt for a priviously sent mail. This delivery receipt only acknowledges that the message could be receipted on the recipients computer.
Replies a mail to all. Returns the data for the message that shall be replied.
Replies a mail. Returns the data for the message that shall be replied.
Resolves a given share reference
Searches for mails.
Sends a mail. The request accepts file fields in upload form that denote referenced files that are going to be appended as attachments. For "text/plain" mail bodies, the JSON boolean field "raw" may be specified inside the body's JSON representation to signal that the text content shall be kept as-is; meaning to keep all formatting intact.
Sends or saves a mail as MIME data block (RFC822).
Updates a mail or a folder's messages and/or moves a mail to another folder.
The update request can perform an update of the color label and flags of one mail object. Beside it is possible to change the mail's folder, meaning move the mail to another folder. Both operations can be performed at once too. If neither parameter id
nor parameter message_id
is specified, all folder's messages are updated accordingly.
Link to this section Functions
autosave(connection, session, opts \\ [])
@spec autosave(Tesla.Env.client(), String.t(), keyword()) :: {:ok, OpenXchangeClient.Model.MailsResponse.t()} | {:error, Tesla.Env.t()}
Auto saves an e-mail as draft.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- opts (KeywordList): [optional] Optional parameters
- :csid (String.t): The "csid" parameter providing the composition space identifier.
- :nested_msgs ([OpenXchangeClient.Model.NestedMailData.t]): An array containing additional mails that are attached to this mail.
- :security_info ([OpenXchangeClient.Model.GuardSecurityInfo.t]): Information if mail is encrypted or signed. Requires Guard
- :security ([OpenXchangeClient.Model.GuardSecurityResult.t]): Information regarding signature verification or decryption type after processed by Guard
- :authenticity (OpenXchangeClient.Model.AuthenticationResult.t):
- :color_label (integer()): Color number used by Outlook to label the object. The assignment of colors to numbers is arbitrary and specified by the client. The numbers are integer numbers between 0 and 10 (inclusive).
- :id (String.t): Object ID of the mail.
- :folder_id (String.t): Object ID of the parent folder.
- :attachment (boolean()): Indicates whether this mail has attachments.
- :from ([[String.t]]): Each element is a two-element array specifying one sender (address). The first element of each address is the personal name, the second element is the email address. Missing address parts are represented by null values.
- :to ([[String.t]]): Each element is a two-element array (see the from field) specifying one receiver.
- :cc ([[String.t]]): Each element is a two-element array (see the from field) specifying one carbon-copy receiver.
- :bcc ([[String.t]]): Each element is a two-element array (see the from field) specifying one blind carbon-copy receiver.
- :subject (String.t): The mail's subject.
- :size (integer()): The size if the mail in bytes.
- :sent_date (integer()): Date and time as specified in the mail by the sending client.
- :received_date (integer()): Date and time as measured by the receiving server.
- :flags (integer()): Various system flags. A sum of zero or more of following values (see javax.mail.Flags.Flag for details).
- :level (integer()): Zero-based nesting level in a thread.
- :disp_notification_to (String.t): Content of message's header \"Disposition-Notification-To\".
- :priority (integer()): Value of message's X-Priority header.
- :msg_ref (String.t): Message reference on reply/forward.
- :flag_seen (String.t): Special field to sort mails by seen status.
- :account_name (String.t): Message's account name.
- :account_id (integer()): Message's account identifier.
- :user ([String.t]): An array with user-defined flags as strings.
- :headers (map()): A map with fields for every non-standard header. The header name is the field name. The header value is the value of the field as string.
- :attachments ([OpenXchangeClient.Model.MailAttachment.t]): Each element is an attachment. The first element is the mail text. If the mail has multiple representations (multipart-alternative), then the alternatives are placed after the mail text and have the field disp set to alternative.
- :truncated (boolean()):
true
/false
if the mail content was trimmed. - :source (String.t): RFC822 source of the mail. Only present for \"?action=get&attach_src=true\".
- :cid (String.t): The value of the \"Content-ID\" header, if the header is present.
- :original_id (String.t): The original mail identifier (e.g. if fetched from \"virtual/all\" folder).
- :original_folder_id (String.t): The original folder identifier (e.g. if fetched from \"virtual/all\" folder).
- :content_type (String.t): The MIME type of the mail.
- :text_preview (String.t): The optional preview of the mail body
returns
Returns
on success {:error, Tesla.Env.t} on failure
clear_mail_folders(connection, session, body, opts \\ [])
@spec clear_mail_folders(Tesla.Env.client(), String.t(), [String.t()], keyword()) :: {:ok, OpenXchangeClient.Model.MailsCleanUpResponse.t()} | {:error, Tesla.Env.t()}
Clears the content of mail folders.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- body ([String.t]): A JSON array with object IDs of the mail folders that shall be cleared.
- opts (KeywordList): [optional] Optional parameters
- :timestamp (integer()): Not IMAP: timestamp of the last update of the deleted mails.
returns
Returns
on success {:error, Tesla.Env.t} on failure
copy_mail(connection, session, id, folder, body, opts \\ [])
@spec copy_mail( Tesla.Env.client(), String.t(), String.t(), String.t(), OpenXchangeClient.Model.MailDestinationBody.t(), keyword() ) :: {:ok, OpenXchangeClient.Model.MailDestinationResponse.t()} | {:error, Tesla.Env.t()}
Copies a mail to another folder.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- id (String.t): Object ID of the requested mail that shall be copied.
- folder (String.t): Object ID of the folder who contains the mails.
- body (MailDestinationBody): A JSON object containing the id of the destination folder.
- opts (KeywordList): [optional] Optional parameters
returns
Returns
on success {:error, Tesla.Env.t} on failure
delete_mails(connection, session, body, opts \\ [])
@spec delete_mails( Tesla.Env.client(), String.t(), [OpenXchangeClient.Model.MailListElement.t()], keyword() ) :: {:ok, OpenXchangeClient.Model.MailsCleanUpResponse.t()} | {:error, Tesla.Env.t()}
Deletes mails.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- body ([OpenXchangeClient.Model.MailListElement.t]): A JSON array of JSON objects with the id and folder of the mails.
- opts (KeywordList): [optional] Optional parameters
- :timestamp (integer()): Not IMAP: timestamp of the last update of the deleted mails.
- :harddelete (boolean()): Flag to hard delete the messages, meaning not to create a backup copy of each message in default trash if set to
true
. - :return_affected_folders (boolean()): Flag to generate an JSON reponse as described below. If set to
false
just an empty JSON Array is returned.
returns
Returns
on success {:error, Tesla.Env.t} on failure
examine(connection, session, folder, opts \\ [])
@spec examine(Tesla.Env.client(), String.t(), String.t(), keyword()) :: {:ok, OpenXchangeClient.Model.ExamineResponse.t()} | {:error, Tesla.Env.t()}
Examines a specifed mail folder and provides its basic status information
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): The identifier of the folder to provide the status information for
- opts (KeywordList): [optional] Optional parameters
returns
Returns
on success {:error, Tesla.Env.t} on failure
forward_mail(connection, session, folder, id, opts \\ [])
@spec forward_mail(Tesla.Env.client(), String.t(), String.t(), String.t(), keyword()) :: {:ok, OpenXchangeClient.Model.MailReplyResponse.t()} | {:error, Tesla.Env.t()}
Forwards a mail. Returns the data for the message that shall be forwarded.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- id (String.t): Object ID of the requested message.
- opts (KeywordList): [optional] Optional parameters
- :view (String.t): Content 'text' forces the server to deliver a text-only version of the requested mail's body, even if content is HTML. 'html' to allow a possible HTML mail body being transferred as it is (but white-list filter applied). NOTE: if set, the corresponding gui config setting will be ignored.
- :max_size (integer()): A positive integer number (greater than 10000) to specify how many characters of the message content will be returned. If the number is smaller than 10000 the value will be ignored and 10000 used.
- :decrypt (boolean()): If true, and the object is encrypted, an attempt will be made to decrypt the object. An error will be thrown if needed authentication isn't available. (Guard Required)
- :crypto_auth (String.t): Authentication token used for Guard in order to decrypt or sign items. Required if the token is not attached to the session and the decrypt flag was sent.
returns
Returns
on success {:error, Tesla.Env.t} on failure
get_all_mails(connection, session, folder, columns, opts \\ [])
@spec get_all_mails(Tesla.Env.client(), String.t(), String.t(), String.t(), keyword()) :: {:ok, OpenXchangeClient.Model.MailsResponse.t()} | {:error, Tesla.Env.t()}
Gets all mails.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- columns (String.t): A comma-separated list of either columns or header names to return, like "600,601,X-Custom-Header". Each column is specified by a numeric column identifier, see Detailed mail data.
- opts (KeywordList): [optional] Optional parameters
- :headers (String.t): A comma-separated list of header names to return, like "From,X-Custom-Header". This parameter can be used in addition to the columns parameter.
- :unseen (boolean()): If
true
only mails without the\Seen
flag are returned. - :deleted (boolean()): If
false
only mails without the\Deleted
flag are returned. - :sort (String.t): The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
- :order (String.t): "asc" if the response entities should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
- :left_hand_limit (integer()): A positive integer number to specify the "left-hand" limit of the range to return.
- :right_hand_limit (integer()): A positive integer number to specify the "right-hand" limit of the range to return.
- :limit (integer()): A positive integer number to specify how many items shall be returned according to given sorting; overrides
left_hand_limit
/right_hand_limit
parameters and is equal toleft_hand_limit=0
andright_hand_limit=<limit>
. - :categoryid (String.t): The category id to filter for. If set to "general" all mails which does not belong to any other category are retrieved.
returns
Returns
on success {:error, Tesla.Env.t} on failure
get_attachments_as_zip(connection, session, folder, id, attachment, opts \\ [])
@spec get_attachments_as_zip( Tesla.Env.client(), String.t(), String.t(), String.t(), String.t(), keyword() ) :: {:ok, String.t()} | {:error, Tesla.Env.t()}
Gets multiple mail attachments as a ZIP file.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- id (String.t): Object ID of the mail which contains the attachments.
- attachment (String.t): A comma-separated list of IDs of the requested attachments.
- opts (KeywordList): [optional] Optional parameters
- :scan (boolean()): Flag to request an Anti-Virus scan for the specified e-mail attachments before downloading them.
returns
Returns
on success {:error, Tesla.Env.t} on failure
get_mail(connection, session, folder, opts \\ [])
@spec get_mail(Tesla.Env.client(), String.t(), String.t(), keyword()) :: {:ok, OpenXchangeClient.Model.MailResponse.t()} | {:error, Tesla.Env.t()}
Gets a mail.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- opts (KeywordList): [optional] Optional parameters
- :id (String.t): Object ID of the requested mail (can be substituded by
message_id
parameter). - :message_id (String.t): The value of "Message-Id" header of the requested mail. This parameter is a substitute for "id" parameter.
- :edit (integer()): 1 indicates that this request should fill the message compose dialog to edit a message and thus display-specific date is going to be withheld.
- :view (String.t): "Specifies the view of the mail's body: raw (returns the content as it is, meaning no preparation are performed and thus no guarantee for safe contents is given), text ( forces the server to deliver a text-only version of the requested mail's body, even if content is HTML), textNoHtmlAttach (is the same as 'text', but does not deliver the HTML part as attachment in case of multipart/alternative content), html (to allow a possible HTML mail body being transferred as it is (but white-list filter applied)), noimg (to allow a possible HTML content being transferred but without original image src attributes which references external images; can be used to prevent loading external linked images (spam privacy protection)). document (to have a inline HTML representation of message's content in a separate window) If set, the corresponding gui config setting will be ignored."
- :force_images (boolean()): Use
true
to enforce that images are allowed in HTML content. Only applicable in caseview
parameter isdocument
- :unseen (boolean()): Use
true
to leave an unseen mail as unseen although its content is requested. - :max_size (integer()): A positive integer number (greater than 10000) to specify how many characters of the message content will be returned. If the number is smaller than 10000 the value will be ignored and 10000 used.
- :attach_src (integer()): 1 to let the JSON mail representation being extended by "source" field containing the mail raw RFC822 source data.
- :estimate_length (boolean()): If set to "true" the "size" field for mail attachments is adjusted by applying an estimation based on attachment's Content-Transfer-Encoding header
- :pregenerate_previews (boolean()): If set to "true" preview generation is triggered in the background for all file attachments of the referenced mail message
- :no_nested_message (boolean()): If set to "true" nested messages are handled as regular attachments
- :decrypt (boolean()): If true, and the object is encrypted, an attempt will be made to decrypt the object. An error will be thrown if needed authentication isn't available. (Guard Required)
- :crypto_auth (String.t): Authentication token used for Guard in order to decrypt or sign items. Required if the token is not attached to the session and the decrypt flag was sent.
- :id (String.t): Object ID of the requested mail (can be substituded by
returns
Returns
on success {:error, Tesla.Env.t} on failure
get_mail_attachment(connection, session, folder, id, opts \\ [])
@spec get_mail_attachment( Tesla.Env.client(), String.t(), String.t(), String.t(), keyword() ) :: {:ok, String.t()} | {:error, Tesla.Env.t()}
Gets a mail attachment.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- id (String.t): Object ID of the mail which contains the attachment.
- opts (KeywordList): [optional] Optional parameters
- :attachment (String.t): ID of the requested attachment (can be substituted by the parameter
cid
otherwise this parameter is madatory). - :cid (String.t): Value of header 'Content-ID' of the requested attachment (can be substituted by the parameter
attachment
otherwise this parameter is madatory). - :save (integer()): 1 overwrites the defined mimetype for this attachment to force the download dialog, otherwise 0.
- :filter (integer()): 1 to apply HTML white-list filter rules if and only if requested attachment is of MIME type
text/htm*
AND parametersave
is set to 0. - :allow_nested_messages (boolean()): A value of "false" leads to light-weight JSON objects for nested messages containing only the "id" field
- :scan (boolean()): Flag to request an Anti-Virus scan for the specified e-mail attachment before downloading it. Note that if there is a max file limitation set on the middleware, the URL parameter 'exact_length' has to be set to 'true' to instruct the middleware to calculate the attachment's size before passing it to the Anti-Virus scanner.
- :as_json (boolean()): Nested messages are parsed into full JSON objects. Can lead to longer loading times, for multiple nested messages.
- :decrypt (boolean()): If true, and the object is encrypted, an attempt will be made to decrypt the object. An error will be thrown if needed authentication isn't available. (Guard Required)
- :crypto_auth (String.t): Authentication token used for Guard in order to decrypt or sign items. Required if the token is not attached to the session and the decrypt flag was sent.
- :rotate (boolean()): Adds a 'rotate' transformation, leading to the image being rotated according to the contained EXIF information.
- :width (integer()): The maximum width of the target image.
- :height (integer()): The maximum height of the target image.
- :shrink_only (boolean()): Set to true to only scale images 'greater than' target size.
- :scale_type (String.t): Defines the scale type. Possible value: <ul> <li><code>cover</code> - The "cover" scale type, specifying the minimum target dimensions. <br> The source image will be resized in a way that the resulting image covers the target resolution entirely, with the original aspect ratio being preserved. For example, scaling an image with an original resolution of 640x480 pixels to 200x200 pixels and type "cover", will result in the picture being resized to 267x200 pixels.</li> <li><code>contain</code> - The "contain" scale type, specifying the maximum target dimensions. <br> The source image will be resized in a way that the resulting image fits into the target resolution entirely, with the original aspect ratio being preserved. For example, scaling an image with an original resolution of 640x480 pixels to 200x200 pixels and type "contain", will result in the picture being resized to 200x150 pixels.</li> <li><code>containforcedimension</code> - The "containforcedimension" scale type, specifying the maximum target dimensions. <br> The source image will be resized in a way that the resulting image fits into the target resolution entirely, with the original aspect ratio being preserved while smaller sides get padded to fit exact dimension. For example, scaling an image with an original resolution of 640x480 pixels to 200x200 pixels and type "containforcedimension", will result in the picture being first resized to 200x150 pixels, then height gets padded by 25 pixels per side resulting in exactly 200x200 pixels.</li> <li><code>coverandcrop</code> - The "coverandcrop" scale type, specifying the target dimensions. <br> If the source image is bigger than the target dimension, in a first step the image will be resized in a way that the resulting image covers the target resolution entirely, with the original aspect ratio being preserved. In a second step the image will be cropped to fit the target dimension. For example, scaling an image with an original resolution of 640x480 pixels to 200x200 pixels and type "coverandcrop", will result in the picture being resized to 267x200 pixels and then cropped to fit 200x200. In case the image is smaller than then target dimension the image will not be resized and instead it gets padded to fit exact dimension. For example, with an original resolution of 100x100 pixels and a target dimension of 200x200 pixels and type "coverandcrop", will result in the picture being padded on all sides with 50 pixels.</li> <li><code>auto</code> - The "auto" scale type.<br></li> </ul>
- :crop_width (integer()): The width of the specified rectangular region.
- :crop_height (integer()): The height of the specified rectangular region.
- :crop_x (integer()): The X coordinate of the upper-left corner of the specified rectangular region.
- :crop_y (integer()): The Y coordinate of the upper-left corner of the specified rectangular region.
- :attachment (String.t): ID of the requested attachment (can be substituted by the parameter
returns
Returns
on success {:error, Tesla.Env.t} on failure
get_mail_conversations(connection, session, folder, columns, opts \\ [])
@spec get_mail_conversations( Tesla.Env.client(), String.t(), String.t(), String.t(), keyword() ) :: {:ok, OpenXchangeClient.Model.MailConversationsResponse.t()} | {:error, Tesla.Env.t()}
Gets all mail conversations.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- columns (String.t): A comma-separated list of either columns or header names to return, like "600,601,X-Custom-Header". Each column is specified by a numeric column identifier, see Detailed mail data.
- opts (KeywordList): [optional] Optional parameters
- :headers (String.t): A comma-separated list of header names to return, like "From,X-Custom-Header". This parameter can be used in addition to the columns parameter.
- :unseen (boolean()): If
true
only mails without the\Seen
flag are returned. - :deleted (boolean()): If
false
only mails without the\Deleted
flag are returned. - :sort (String.t): The identifier of a column which determines the sort order of the response or the string “thread” to return thread-sorted messages. If this parameter is specified and holds a column number, then the parameter order must be also specified. Note: Applies only to root-level messages.
- :order (String.t): "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified. Note: Applies only to root-level messages.
- :include_sent (boolean()): A boolean value to signal that conversations also include messages taken from special "sent" aka "sent items" folder.
- :left_hand_limit (integer()): A positive integer number to specify the "left-hand" limit of the range to return. Note: Applies only to root-level messages.
- :right_hand_limit (integer()): A positive integer number to specify the "right-hand" limit of the range to return. Note: Applies only to root-level messages.
- :limit (integer()): A positive integer number to specify how many items shall be returned according to given sorting; overrides
left_hand_limit
/right_hand_limit
parameters and is equal toleft_hand_limit=0
andright_hand_limit=<limit>
. Note: Applies only to root-level messages. - :categoryid (String.t): The category id to filter for. Retrieves all conversations with at least one mail in the category.
- :max (String.t): The max. number of messages to consider.
returns
Returns
on success {:error, Tesla.Env.t} on failure
get_mail_count(connection, session, folder, opts \\ [])
@spec get_mail_count(Tesla.Env.client(), String.t(), String.t(), keyword()) :: {:ok, OpenXchangeClient.Model.MailCountResponse.t()} | {:error, Tesla.Env.t()}
Gets the mail count.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- opts (KeywordList): [optional] Optional parameters
returns
Returns
on success {:error, Tesla.Env.t} on failure
get_mail_headers(connection, session, folder, opts \\ [])
@spec get_mail_headers(Tesla.Env.client(), String.t(), String.t(), keyword()) :: {:ok, OpenXchangeClient.Model.MailHeadersResponse.t()} | {:error, Tesla.Env.t()}
Gets the message headers as plain text.
Note By setting the query parameter hdr
to 1 the response type of the request action changes. Then it is returned a JSON object with the field data
containing the (formatted) message headers as plain text. The parameters below specify the ones that have an effect on the request.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- opts (KeywordList): [optional] Optional parameters
- :id (String.t): Object ID of the requested mail (can be substituded by
message_id
parameter). - :message_id (String.t): The value of "Message-Id" header of the requested mail. This parameter is a substitute for "id" parameter.
- :unseen (boolean()): Use
true
to leave an unseen mail as unseen although its content is requested.
- :id (String.t): Object ID of the requested mail (can be substituded by
returns
Returns
on success {:error, Tesla.Env.t} on failure
get_mail_list(connection, session, columns, body, opts \\ [])
@spec get_mail_list( Tesla.Env.client(), String.t(), String.t(), [OpenXchangeClient.Model.MailListElement.t()], keyword() ) :: {:ok, OpenXchangeClient.Model.MailsResponse.t()} | {:error, Tesla.Env.t()}
Gets a list of mails.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- columns (String.t): A comma-separated list of either columns or header names to return, like "600,601,X-Custom-Header". Each column is specified by a numeric column identifier, see Detailed mail data.
- body ([OpenXchangeClient.Model.MailListElement.t]): A JSON array of JSON objects with the id and folder of the requested mails.
- opts (KeywordList): [optional] Optional parameters
- :headers (String.t): A comma-separated list of header names to return, like "From,X-Custom-Header". This parameter can be used in addition to the columns parameter.
returns
Returns
on success {:error, Tesla.Env.t} on failure
get_mail_source(connection, session, folder, opts \\ [])
@spec get_mail_source(Tesla.Env.client(), String.t(), String.t(), keyword()) :: {:ok, OpenXchangeClient.Model.MailSourceResponse.t()} | {:error, Tesla.Env.t()}
Gets the complete message source as plain text.
Note By setting the query parameter src
to 1 the response type of the request action changes. Then it is returned a JSON object with the field data
containing the complete message source as plain text. The parameters below specify the ones that have an effect on the request.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- opts (KeywordList): [optional] Optional parameters
- :id (String.t): Object ID of the requested mail (can be substituded by
message_id
parameter). - :message_id (String.t): The value of "Message-Id" header of the requested mail. This parameter is a substitute for "id" parameter.
- :unseen (boolean()): Use
true
to leave an unseen mail as unseen although its content is requested. - :save (integer()): 1 to write the complete message source to output stream. NOTE: This parameter will only be used if parameter
src
is set to 1.
- :id (String.t): Object ID of the requested mail (can be substituded by
returns
Returns
on success {:error, Tesla.Env.t} on failure
get_mail_updates(connection, session, folder, columns, opts \\ [])
@spec get_mail_updates( Tesla.Env.client(), String.t(), String.t(), String.t(), keyword() ) :: {:ok, OpenXchangeClient.Model.MailsResponse.t()} | {:error, Tesla.Env.t()}
Gets updated mails. Provides a list of updated mails. Attention: This does not work for IMAP mail accounts. In case of imap accounts an empty list is returned.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- columns (String.t): A comma-separated list of either columns or header names to return, like "600,601,X-Custom-Header". Each column is specified by a numeric column identifier, see Detailed mail data.
- opts (KeywordList): [optional] Optional parameters
- :headers (String.t): A comma-separated list of header names to return, like "From,X-Custom-Header". This parameter can be used in addition to the columns parameter.
- :ignore (String.t): The type of updates which should be ignored. Currently known values are 'deleted' and 'changed'. E.g. if you only want to retrieve deleted mails you use 'ignore=changed'.
returns
Returns
on success {:error, Tesla.Env.t} on failure
get_mails_as_zip(connection, session, folder, id, opts \\ [])
@spec get_mails_as_zip( Tesla.Env.client(), String.t(), String.t(), String.t(), keyword() ) :: {:ok, String.t()} | {:error, Tesla.Env.t()}
Gets multiple mails as a ZIP file.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- id (String.t): A comma-separated list of Object IDs of the requested mails.
- opts (KeywordList): [optional] Optional parameters
returns
Returns
on success {:error, Tesla.Env.t} on failure
get_thread_references(connection, session, folder, columns, opts \\ [])
@spec get_thread_references( Tesla.Env.client(), String.t(), String.t(), String.t(), keyword() ) :: {:ok, OpenXchangeClient.Model.MailThreadReferencesResponse.t()} | {:error, Tesla.Env.t()}
Gets all mail thread references.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- columns (String.t): A comma-separated list of either columns or header names to return, like "600,601,X-Custom-Header". Each column is specified by a numeric column identifier, see Detailed mail data.
- opts (KeywordList): [optional] Optional parameters
- :headers (String.t): A comma-separated list of header names to return, like "From,X-Custom-Header". This parameter can be used in addition to the columns parameter.
- :sort (String.t): The identifier of a column which determines the sort order of the response or the string “thread” to return thread-sorted messages. If this parameter is specified and holds a column number, then the parameter order must be also specified. Note: Applies only to root-level messages.
- :order (String.t): "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified. Note: Applies only to root-level messages.
- :size (integer()): The optional number of latest messages to consider.
returns
Returns
on success {:error, Tesla.Env.t} on failure
import_mail(connection, session, folder, file, opts \\ [])
@spec import_mail(Tesla.Env.client(), String.t(), String.t(), String.t(), keyword()) :: {:ok, OpenXchangeClient.Model.MailImportResponse.t()} | {:error, Tesla.Env.t()}
Import of mails as MIME data block (RFC822). This request can be used to store a single or a lot of mails in the OX mail storage backend. This action should be used instead of /mail?action=new because it is faster and tolerant to 8-bit encoded emails. To import multiple mails add further form-data fields.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): The ID of the folder into that the emails should be imported.
- file (String.t): The RFC822 encoded email as binary data.
- opts (KeywordList): [optional] Optional parameters
- :flags (String.t): In case the mail should be stored with status "read" (e.g. mail has been read already in the client inbox), the parameter "flags" has to be included. For information about mail flags see Detailed mail data.
- :force (boolean()): If this parameter is set to
true
, the server skips checking the valid from address.
returns
Returns
on success {:error, Tesla.Env.t} on failure
mark_all_mails_as_read(connection, session, folder, opts \\ [])
@spec mark_all_mails_as_read(Tesla.Env.client(), String.t(), String.t(), keyword()) :: {:ok, OpenXchangeClient.Model.MailsAllSeenResponse.t()} | {:error, Tesla.Env.t()}
Marks all mails of a folder as seen.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- opts (KeywordList): [optional] Optional parameters
returns
Returns
on success {:error, Tesla.Env.t} on failure
put_mail_attachment(connection, session, folder, id, attachment, dest_folder, body, opts \\ [])
@spec put_mail_attachment( Tesla.Env.client(), String.t(), String.t(), String.t(), String.t(), String.t(), OpenXchangeClient.Model.PutAttachmentBody.t(), keyword() ) :: {:ok, OpenXchangeClient.Model.InlineResponse200.t()} | {:error, Tesla.Env.t()}
Stores a mail attachment to the drive.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- id (String.t): Object ID of the mail which contains the attachment.
- attachment (String.t): ID of the requested attachment.
- dest_folder (String.t): Object ID of the folder in which the attachment should be stored.
- body (PutAttachmentBody): A possible empty JSON object containing the optional fields
description
andfilename
. The filename and description values will be used for the newly created file in the drive module. - opts (KeywordList): [optional] Optional parameters
returns
Returns
on success {:error, Tesla.Env.t} on failure
receipt_mail_ack(connection, session, body, opts \\ [])
@spec receipt_mail_ack( Tesla.Env.client(), String.t(), OpenXchangeClient.Model.MailAckBody.t(), keyword() ) :: {:ok, OpenXchangeClient.Model.MailAckResponse.t()} | {:error, Tesla.Env.t()}
Requests a delivery receipt for a priviously sent mail. This delivery receipt only acknowledges that the message could be receipted on the recipients computer.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- body (MailAckBody): A JSON object containing the information of a mail for which a delivery receipt shall be requested.
- opts (KeywordList): [optional] Optional parameters
returns
Returns
on success {:error, Tesla.Env.t} on failure
reply_all_mail(connection, session, folder, id, opts \\ [])
@spec reply_all_mail( Tesla.Env.client(), String.t(), String.t(), String.t(), keyword() ) :: {:ok, OpenXchangeClient.Model.MailReplyResponse.t()} | {:error, Tesla.Env.t()}
Replies a mail to all. Returns the data for the message that shall be replied.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- id (String.t): Object ID of the requested message.
- opts (KeywordList): [optional] Optional parameters
- :view (String.t): Content 'text' forces the server to deliver a text-only version of the requested mail's body, even if content is HTML. 'html' to allow a possible HTML mail body being transferred as it is (but white-list filter applied). NOTE: if set, the corresponding gui config setting will be ignored.
- :set_from (boolean()): A flag (
true
/false
) that signals if "From" header shall be pre-selected according to a suitable recipient address that matches one of user's email address aliases. - :max_size (integer()): A positive integer number (greater than 10000) to specify how many characters of the message content will be returned. If the number is smaller than 10000 the value will be ignored and 10000 used.
- :decrypt (boolean()): If true, and the object is encrypted, an attempt will be made to decrypt the object. An error will be thrown if needed authentication isn't available. (Guard Required)
- :crypto_auth (String.t): Authentication token used for Guard in order to decrypt or sign items. Required if the token is not attached to the session and the decrypt flag was sent.
returns
Returns
on success {:error, Tesla.Env.t} on failure
reply_mail(connection, session, folder, id, opts \\ [])
@spec reply_mail(Tesla.Env.client(), String.t(), String.t(), String.t(), keyword()) :: {:ok, OpenXchangeClient.Model.MailReplyResponse.t()} | {:error, Tesla.Env.t()}
Replies a mail. Returns the data for the message that shall be replied.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- id (String.t): Object ID of the requested message.
- opts (KeywordList): [optional] Optional parameters
- :view (String.t): Content 'text' forces the server to deliver a text-only version of the requested mail's body, even if content is HTML. 'html' to allow a possible HTML mail body being transferred as it is (but white-list filter applied). NOTE: if set, the corresponding gui config setting will be ignored.
- :set_from (boolean()): A flag (
true
/false
) that signals if "From" header shall be pre-selected according to a suitable recipient address that matches one of user's E-Mail address aliases. - :max_size (integer()): A positive integer number (greater than 10000) to specify how many characters of the message content will be returned. If the number is smaller than 10000 the value will be ignored and 10000 used.
- :decrypt (boolean()): If true, and the object is encrypted, an attempt will be made to decrypt the object. An error will be thrown if needed authentication isn't available. (Guard Required)
- :crypto_auth (String.t): Authentication token used for Guard in order to decrypt or sign items. Required if the token is not attached to the session and the decrypt flag was sent.
returns
Returns
on success {:error, Tesla.Env.t} on failure
search_mails(connection, session, folder, columns, body, opts \\ [])
@spec search_mails( Tesla.Env.client(), String.t(), String.t(), String.t(), String.t(), keyword() ) :: {:ok, OpenXchangeClient.Model.MailsResponse.t()} | {:error, Tesla.Env.t()}
Searches for mails.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- columns (String.t): A comma-separated list of either columns or header names to return, like "600,601,X-Custom-Header". Each column is specified by a numeric column identifier, see Detailed mail data.
- body (String.t): A JSON object describing the search term as described in Advanced search. Example:
{"filter":["and",["=", {"field":"to"},"test1@example.com"],["not",["=",{"attachment":"name"},"document.pdf"]]]}
which represents 'to = "test1@example.com" AND NOT from = "test2@example.com"'. Available field names arefrom
,to
,cc
,bcc
,subject
,received_date
,sent_date
,size
,flags
,content
,content_type
,disp
, andpriority
. - opts (KeywordList): [optional] Optional parameters
- :headers (String.t): A comma-separated list of header names to return, like "From,X-Custom-Header". This parameter can be used in addition to the columns parameter.
- :unseen (boolean()): If
true
only mails without the\Seen
flag are returned. - :deleted (boolean()): If
false
only mails without the\Deleted
flag are returned. - :sort (String.t): The identifier of a column which determines the sort order of the response or the string “thread” to return thread-sorted messages. If this parameter is specified and holds a column number, then the parameter order must be also specified. Note: Applies only to root-level messages.
- :order (String.t): "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified. Note: Applies only to root-level messages.
returns
Returns
on success {:error, Tesla.Env.t} on failure
send_mail(connection, session, json0, opts \\ [])
@spec send_mail(Tesla.Env.client(), String.t(), String.t(), keyword()) :: {:ok, String.t()} | {:error, Tesla.Env.t()}
Sends a mail. The request accepts file fields in upload form that denote referenced files that are going to be appended as attachments. For "text/plain" mail bodies, the JSON boolean field "raw" may be specified inside the body's JSON representation to signal that the text content shall be kept as-is; meaning to keep all formatting intact.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- json0 (String.t): 'Contains the rudimentary mail as JSON object as described in Detailed mail data with just its message body (as html content) defined in nested JSON array
attachments
and its header data (from, to, subject, etc.). The field \"content_type\" defines whether the mail ought to be sent as plain text (\"text/plain\"), as html (\"text/html\") or as multipart/alternative (\"ALTERNATIVE\"). Sending a mail requires some special fields inside JSON mail object. The field \"infostore_ids\" defines a JSON array of infostore document ID(s) that ought to be appended to this mail as attachments. The field \"msgref\" indicates the ID of the referenced original mail. Moreover the field \"sendtype\" indicates the type of the message: <br> 0 (normal new mail),<br> 1 (a reply mail, fieldmsgref
must be present),<br> 2 (a forward mail, fieldmsgref
must be present),<br> 3 (draft edit operation, fieldmsgref
must be present in order to delete previous draft message since e.g. IMAP does not support changing/replacing a message but requires a delete-and-insert sequence),<br> 4 (transport of a draft mail, fieldmsgref
must be present),<br> 6 (signals that user intends to send out a saved draft message and expects the draft message (referenced bymsgref
field) being deleted after successful transport).' - opts (KeywordList): [optional] Optional parameters
- :line_wrap_after (integer()): An integer value specifying the line-wrap setting (only effective for plain-text content); if absent the setting is taken from user's mail settings.
returns
Returns
on success {:error, Tesla.Env.t} on failure
send_or_save_mail(connection, session, opts \\ [])
@spec send_or_save_mail(Tesla.Env.client(), String.t(), keyword()) :: {:ok, OpenXchangeClient.Model.MailDestinationResponse.t()} | {:error, Tesla.Env.t()}
Sends or saves a mail as MIME data block (RFC822).
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- opts (KeywordList): [optional] Optional parameters
- :folder (String.t): In case the mail should not be sent out, but saved in a specific folder, the "folder" parameter can be used. If the mail should be sent out to the recipient, the "folder" parameter must not be included and the mail is stored in the folder "Sent Items".
- :flags (String.t): In case the mail should be stored with status "read" (e.g. mail has been read already in the client inbox), the parameter "flags" has to be included. If no
folder
parameter is specified, this parameter must not be included. For information about mail flags see Mail data model.
returns
Returns
on success {:error, Tesla.Env.t} on failure
update_mail(connection, session, folder, body, opts \\ [])
@spec update_mail( Tesla.Env.client(), String.t(), String.t(), OpenXchangeClient.Model.MailUpdateBody.t(), keyword() ) :: {:ok, OpenXchangeClient.Model.MailDestinationResponse.t()} | {:error, Tesla.Env.t()}
Updates a mail or a folder's messages and/or moves a mail to another folder.
The update request can perform an update of the color label and flags of one mail object. Beside it is possible to change the mail's folder, meaning move the mail to another folder. Both operations can be performed at once too. If neither parameter id
nor parameter message_id
is specified, all folder's messages are updated accordingly.
parameters
Parameters
- connection (OpenXchangeClient.Connection): Connection to server
- session (String.t): A session ID previously obtained from the login module.
- folder (String.t): Object ID of the folder who contains the mails.
- body (MailUpdateBody): A JSON object containing the new values that ought to be applied to mail and/or the id of the destination folder (if the mail shall be moved, otherwise it must not be specified).
- opts (KeywordList): [optional] Optional parameters
- :id (String.t): Object ID of the requested mail that shall be updated (mandatory if a mail shall be moved).
- :message_id (String.t): The value of "Message-Id" header of the requested mail. This parameter is a substitute for "id" parameter.
returns
Returns
on success {:error, Tesla.Env.t} on failure