Tizen Native API
7.0
|
The Email API provides functions to create, set properties and send email.
Required Header
#include <email.h>
Overview
The Email API provides functions that prepare and send email messages. This API allows email message creation, setting message properties and sending as well setting up to be notified when the email message has been sent.
Email, short for electronic mail, is a method of exchanging digital messages. This API allows you to send email using SMTP. Simple Mail Transfer Protocol (SMTP) used for sending email via Internet is described in RFC5321/5322 standards.
The Email API consists of functions that:
- Set the subject, body and recipients of an email message
- Set the file path for attaching files to an email message
- Send an email message
- Register/unregister a callback function to be called when the sending process is complete, whether it is sent successfully or not
Related Features
This API is related with the following features:
- http://tizen.org/feature/email
It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.
Email sending is asynchronous and the application should not wait for the result. Not only may the process be slow (connections to be established and so on), but even if the mail server is not available a message send may not be a failure, if there is a spooling mechanism. Instead, the callback function is used to receive status. In addition, note that once email_send_message() is called, the message contents are out of the application's hands. Even if the message appears not to have finished sending, it can no longer be modified.
Callback(Event) Operations
REGISTER | UNREGISTER | CALLBACK | DESCRIPTION |
---|---|---|---|
email_set_message_sent_cb() | email_unset_message_sent_cb() | email_message_sent_cb() | Registering/unregistering a callback function to check whether an email message is sent successfully or not |
Functions | |
int | email_create_message (email_h *email) |
Creates an email message handle for sending an email message. | |
int | email_destroy_message (email_h email) |
Destroys the email message handle and releases all its resources. | |
int | email_set_subject (email_h email, const char *subject) |
Sets a subject of the email message. | |
int | email_set_body (email_h email, const char *body) |
Populates a body of the email message. | |
int | email_add_recipient (email_h email, email_recipient_type_e type, const char *address) |
Adds a recipient to the email message. | |
int | email_remove_all_recipients (email_h email) |
Removes all recipients for the email message. | |
int | email_add_attach (email_h email, const char *filepath) |
Adds a file as an attachment to the email message. | |
int | email_remove_all_attachments (email_h email) |
Clears all attachments of the email message. | |
int | email_save_message (email_h email) |
Saves the email message at outbox. | |
int | email_send_message (email_h email, bool save_to_sentbox) |
Sends the email message. | |
int | email_set_message_sent_cb (email_h email, email_message_sent_cb callback, void *user_data) |
Registers a callback function to be invoked when an email message is sent. | |
int | email_unset_message_sent_cb (email_h msg) |
Unregisters the callback function. | |
Typedefs | |
typedef void(* | email_message_sent_cb )(email_h email, email_sending_e result, void *user_data) |
Called when the process of sending an email finishes. | |
typedef struct email_s * | email_h |
The email message handle. |
Typedef Documentation
typedef struct email_s* email_h |
The email message handle.
- Since :
- 2.3
typedef void(* email_message_sent_cb)(email_h email, email_sending_e result, void *user_data) |
Called when the process of sending an email finishes.
You can check whether sending an email succeeds using this function.
- Since :
- 2.3
- Parameters:
-
[in] email The handle to the email message [in] result The result of email message sending
EMAIL_SENDING_FAILED or EMAIL_SENDING_SUCCEEDED[in] user_data The user data passed from the callback registration function
- Precondition:
- email_send_message() will invoke this callback if you register this callback using email_set_message_sent_cb().
Enumeration Type Documentation
enum email_error_e |
Enumeration for error codes for email API.
- Since :
- 2.3
- Enumerator:
enum email_sending_e |
Function Documentation
int email_add_attach | ( | email_h | email, |
const char * | filepath | ||
) |
Adds a file as an attachment to the email message.
It should be used to add a file to the attachment list of the email message.
- Since :
- 2.3
- Remarks:
- The maximum attachment file size is 10MB. http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
- Parameters:
-
[in] email The handle to the email message [in] filepath The absolute full path of the file to be attached
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
EMAILS_ERROR_NONE Successful EMAILS_ERROR_INVALID_PARAMETER Invalid parameter EMAILS_ERROR_OUT_OF_MEMORY Out of memory EMAILS_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method EMAILS_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- An email message handle is created using email_create_message().
- See also:
- email_remove_all_attachments()
int email_add_recipient | ( | email_h | email, |
email_recipient_type_e | type, | ||
const char * | address | ||
) |
Adds a recipient to the email message.
The email API supports sending an email message to multiple recipients.
- Since :
- 2.3
- Remarks:
- Email address should be in standard format (as described in Internet standards RFC 5321 and RFC 5322).
- Parameters:
-
[in] email The handle to the email message [in] type The recipient type [in] address The recipient email address
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
EMAILS_ERROR_NONE Successful EMAILS_ERROR_INVALID_PARAMETER Invalid parameter EMAILS_ERROR_OUT_OF_MEMORY Out of memory EMAILS_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- An email message handle is created using email_create_message().
int email_create_message | ( | email_h * | ) |
Creates an email message handle for sending an email message.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/email
- Remarks:
- You must release email using email_destroy_message().
- Parameters:
-
[out] email A handle to the email message
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
EMAILS_ERROR_NONE Successful EMAILS_ERROR_OUT_OF_MEMORY Out of memory EMAILS_ERROR_ACCOUNT_NOT_FOUND Email account not found EMAILS_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method EMAILS_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- At least one email account should be set up on the device.
- See also:
- email_destroy_message()
int email_destroy_message | ( | email_h | ) |
Destroys the email message handle and releases all its resources.
- Since :
- 2.3
- Parameters:
-
[in] email The handle to the email message
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
EMAILS_ERROR_NONE Successful EMAILS_ERROR_INVALID_PARAMETER Invalid parameter EMAILS_ERROR_OPERATION_FAILED Operation failed EMAILS_ERROR_NOT_SUPPORTED Not supported
- See also:
- email_create_message()
int email_remove_all_attachments | ( | email_h | ) |
Clears all attachments of the email message.
- Since :
- 2.3
- Parameters:
-
[in] email The handle to the email message
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
EMAILS_ERROR_NONE Successful EMAILS_ERROR_INVALID_PARAMETER Invalid parameter EMAILS_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- An email message handle is created using email_create_message().
- See also:
- email_create_message()
- email_add_attach()
int email_remove_all_recipients | ( | email_h | ) |
Removes all recipients for the email message.
- Since :
- 2.3
- Parameters:
-
[in] email The handle to the email message
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
EMAILS_ERROR_NONE Successful EMAILS_ERROR_INVALID_PARAMETER Invalid parameter EMAILS_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- An email message handle is created using email_create_message().
- See also:
- email_add_recipient()
int email_save_message | ( | email_h | ) |
Saves the email message at outbox.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/email
- Parameters:
-
[in] email The handle to the email message
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
EMAILS_ERROR_NONE Successful EMAILS_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed. EMAILS_ERROR_INVALID_PARAMETER Invalid parameter EMAILS_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method EMAILS_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- An email message handle is created using email_create_message().
int email_send_message | ( | email_h | email, |
bool | save_to_sentbox | ||
) |
Sends the email message.
- Since :
- 2.3
- Remarks:
- In order to check whether sending a message succeeds, you should register email_message_sent_cb() using email_set_message_sent_cb().
- Parameters:
-
[in] email The handle to the email message [in] save_to_sentbox Set to true
to save the message in the sentbox, otherwise set tofalse
to not save the message in the sentbox
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
EMAILS_ERROR_NONE Successful EMAILS_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed EMAILS_ERROR_INVALID_PARAMETER Invalid parameter EMAILS_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- An email message is stored using email_save_message().
int email_set_body | ( | email_h | email, |
const char * | body | ||
) |
Populates a body of the email message.
Email message body means the text data to be delivered.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/mediastorage
- Parameters:
-
[in] email The handle to the email message [in] body The message body
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
EMAILS_ERROR_NONE Successful EMAILS_ERROR_INVALID_PARAMETER Invalid parameter EMAILS_ERROR_OPERATION_FAILED Operation failed EMAILS_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method EMAILS_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- An email message handle is created using email_create_message().
- See also:
- email_create_message()
int email_set_message_sent_cb | ( | email_h | email, |
email_message_sent_cb | callback, | ||
void * | user_data | ||
) |
Registers a callback function to be invoked when an email message is sent.
You will be notified when sending a message finishes and check whether it succeeds using this function.
- Since :
- 2.3
- Parameters:
-
[in] email The handle to the email message [in] callback The callback function to register [in] user_data The user data to be passed to the callback function
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
EMAILS_ERROR_NONE Successful EMAILS_ERROR_INVALID_PARAMETER Invalid parameter EMAILS_ERROR_NOT_SUPPORTED Not supported
- Postcondition:
- It will invoke email_message_sent_cb().
int email_set_subject | ( | email_h | email, |
const char * | subject | ||
) |
Sets a subject of the email message.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/email
- Parameters:
-
[in] email The handle to the email message [in] subject The subject of the email message
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
EMAILS_ERROR_NONE Successful EMAILS_ERROR_INVALID_PARAMETER Invalid parameter EMAILS_ERROR_OUT_OF_MEMORY Out of memory EMAILS_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method EMAILS_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- An email message handle is created using email_create_message().
- See also:
- email_create_message()
int email_unset_message_sent_cb | ( | email_h | msg | ) |
Unregisters the callback function.
- Since :
- 2.3
- Parameters:
-
[in] msg The handle to the email message
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
EMAILS_ERROR_NONE Successful EMAILS_ERROR_INVALID_PARAMETER Invalid parameter EMAILS_ERROR_NOT_SUPPORTED Not supported