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().

See also:: email_send_message(); email_set_message_sent_cb(); email_unset_message_sent_cb()

Enumeration Type Documentation

enum email_error_e

Enumeration for error codes for email API.

Since :: 2.3

Enumerator:

EMAILS_ERROR_NONE	Successful
EMAILS_ERROR_OUT_OF_MEMORY	Memory cannot be allocated
EMAILS_ERROR_INVALID_PARAMETER	Invalid parameter
EMAILS_ERROR_SERVER_NOT_READY	Server not ready
EMAILS_ERROR_COMMUNICATION_WITH_SERVER_FAILED	Communication with server failed
EMAILS_ERROR_OPERATION_FAILED	Operation failed
EMAILS_ERROR_ACCOUNT_NOT_FOUND	Email account not found
EMAILS_ERROR_DB_FAILED	Email database failed
EMAILS_ERROR_PERMISSION_DENIED	Permission denied
EMAILS_ERROR_NOT_SUPPORTED	Not supported (Since 3.0)

enum email_recipient_type_e

Enumeration for the email recipient types.

Since :: 2.3

Enumerator:

EMAIL_RECIPIENT_TYPE_TO	Normal recipient
EMAIL_RECIPIENT_TYPE_CC	CC(carbon copy) recipient
EMAIL_RECIPIENT_TYPE_BCC	BCC(blind carbon copy) recipient

enum email_sending_e

Enumeration for the result values of email transport.

Since :: 2.3

Enumerator:

EMAIL_SENDING_FAILED	Email sending failed
EMAIL_SENDING_SUCCEEDED	Email sending succeeded

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().

See also:: email_create_message(); email_remove_all_recipients()

int email_create_message ( email_h * email )

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 email )

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 email )

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 email )

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 email )

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().

See also:: email_create_message(); email_add_recipient(); email_set_body(); email_save_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 to `false` 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().

See also:: email_save_message(); email_set_message_sent_cb()

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().

See also:: email_message_sent_cb(); email_unset_message_sent_cb(); email_send_message()

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

See also:: email_message_sent_cb(); email_set_message_sent_cb(); email_send_message()

Required Header

Overview

Related Features

Callback(Event) Operations

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation