Tizen(Headed) Native API  6.5

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]emailThe handle to the email message
[in]resultThe result of email message sending
EMAIL_SENDING_FAILED or EMAIL_SENDING_SUCCEEDED
[in]user_dataThe 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

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)

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

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]emailThe handle to the email message
[in]filepathThe absolute full path of the file to be attached
Returns:
0 on success, otherwise a negative error value
Return values:
EMAILS_ERROR_NONESuccessful
EMAILS_ERROR_INVALID_PARAMETERInvalid parameter
EMAILS_ERROR_OUT_OF_MEMORYOut of memory
EMAILS_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
EMAILS_ERROR_NOT_SUPPORTEDNot 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]emailThe handle to the email message
[in]typeThe recipient type
[in]addressThe recipient email address
Returns:
0 on success, otherwise a negative error value
Return values:
EMAILS_ERROR_NONESuccessful
EMAILS_ERROR_INVALID_PARAMETERInvalid parameter
EMAILS_ERROR_OUT_OF_MEMORYOut of memory
EMAILS_ERROR_NOT_SUPPORTEDNot 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]emailA handle to the email message
Returns:
0 on success, otherwise a negative error value
Return values:
EMAILS_ERROR_NONESuccessful
EMAILS_ERROR_OUT_OF_MEMORYOut of memory
EMAILS_ERROR_ACCOUNT_NOT_FOUNDEmail account not found
EMAILS_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
EMAILS_ERROR_NOT_SUPPORTEDNot supported
Precondition:
At least one email account should be set up on the device.
See also:
email_destroy_message()

Destroys the email message handle and releases all its resources.

Since :
2.3
Parameters:
[in]emailThe handle to the email message
Returns:
0 on success, otherwise a negative error value
Return values:
EMAILS_ERROR_NONESuccessful
EMAILS_ERROR_INVALID_PARAMETERInvalid parameter
EMAILS_ERROR_OPERATION_FAILEDOperation failed
EMAILS_ERROR_NOT_SUPPORTEDNot supported
See also:
email_create_message()

Clears all attachments of the email message.

Since :
2.3
Parameters:
[in]emailThe handle to the email message
Returns:
0 on success, otherwise a negative error value
Return values:
EMAILS_ERROR_NONESuccessful
EMAILS_ERROR_INVALID_PARAMETERInvalid parameter
EMAILS_ERROR_NOT_SUPPORTEDNot supported
Precondition:
An email message handle is created using email_create_message().
See also:
email_create_message()
email_add_attach()

Removes all recipients for the email message.

Since :
2.3
Parameters:
[in]emailThe handle to the email message
Returns:
0 on success, otherwise a negative error value
Return values:
EMAILS_ERROR_NONESuccessful
EMAILS_ERROR_INVALID_PARAMETERInvalid parameter
EMAILS_ERROR_NOT_SUPPORTEDNot 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]emailThe handle to the email message
Returns:
0 on success, otherwise a negative error value
Return values:
EMAILS_ERROR_NONESuccessful
EMAILS_ERROR_COMMUNICATION_WITH_SERVER_FAILEDCommunication with server failed.
EMAILS_ERROR_INVALID_PARAMETERInvalid parameter
EMAILS_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
EMAILS_ERROR_NOT_SUPPORTEDNot supported
Precondition:
An email message handle is created using email_create_message().
See also:
email_create_message()
email_add_recipient()
email_set_body()
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]emailThe handle to the email message
[in]save_to_sentboxSet 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_NONESuccessful
EMAILS_ERROR_COMMUNICATION_WITH_SERVER_FAILEDCommunication with server failed
EMAILS_ERROR_INVALID_PARAMETERInvalid parameter
EMAILS_ERROR_NOT_SUPPORTEDNot 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]emailThe handle to the email message
[in]bodyThe message body
Returns:
0 on success, otherwise a negative error value
Return values:
EMAILS_ERROR_NONESuccessful
EMAILS_ERROR_INVALID_PARAMETERInvalid parameter
EMAILS_ERROR_OPERATION_FAILEDOperation failed
EMAILS_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
EMAILS_ERROR_NOT_SUPPORTEDNot 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]emailThe handle to the email message
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
EMAILS_ERROR_NONESuccessful
EMAILS_ERROR_INVALID_PARAMETERInvalid parameter
EMAILS_ERROR_NOT_SUPPORTEDNot 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]emailThe handle to the email message
[in]subjectThe subject of the email message
Returns:
0 on success, otherwise a negative error value
Return values:
EMAILS_ERROR_NONESuccessful
EMAILS_ERROR_INVALID_PARAMETERInvalid parameter
EMAILS_ERROR_OUT_OF_MEMORYOut of memory
EMAILS_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
EMAILS_ERROR_NOT_SUPPORTEDNot supported
Precondition:
An email message handle is created using email_create_message().
See also:
email_create_message()

Unregisters the callback function.

Since :
2.3
Parameters:
[in]msgThe handle to the email message
Returns:
0 on success, otherwise a negative error value
Return values:
EMAILS_ERROR_NONESuccessful
EMAILS_ERROR_INVALID_PARAMETERInvalid parameter
EMAILS_ERROR_NOT_SUPPORTEDNot supported
See also:
email_message_sent_cb()
email_set_message_sent_cb()
email_send_message()