Mobile native

Email: Managing Emails

This tutorial demonstrates how you can send email messages with attachments.

This feature is supported in mobile applications only.

Warm-up

Become familiar with the Email API basics by learning about:

Initializing the Email Service

To initialize the email service:

  1. To use the functions and data types of the Email API, include the <email.h> header file in your application:

    #include <email.h>
    
  2. Set up at least 1 email account on your device before sending an email.

The email service does not need any initialization or connection opening before the API usage.

Creating and Sending Email

To create and send email messages:

  1. Create an email message.

    To create an email message and receive its handle, use the email_create_message() function. The function return code informs about success or failure:

    email_h msg;
    int error_code = EMAILS_ERROR_NONE;
    error_code = email_create_message(&msg);
    if (error_code != EMAILS_ERROR_NONE) 
    {
       dlog_print(DLOG_INFO, LOG_TAG, "Failed to create email message\n");
    }

    One of the possible error codes that is not related to the Email module itself is EMAIL_ERROR_ACCOUNT_NOT_FOUND. This error occurs if no email account has been configured on a device.

  2. Add recipients and attachments.

    Email recipients can be added to the email message one by one. There is no possibility to add lists of recipients in one function call. Each address has to be given as a character string and the address type (TO, CC, BCC) has to be declared:

    error_code = email_add_recipient(msg, EMAIL_RECIPIENT_TYPE_TO, "example@mail.com");
    if (error_code != EMAILS_ERROR_NONE) 
    {
       dlog_print(DLOG_INFO, LOG_TAG, "Failed to add recipient\n");
    }

    To add an attachment to the email message, you need a full path to the attachment file. Currently, files with size up to 10 MB are supported.

    error_code = email_add_attach(msg, "/full/path/to/attachment");
    if (error_code != EMAILS_ERROR_NONE) 
    {
       dlog_print(DLOG_INFO, LOG_TAG, "Failed to add attachment\n");
    }
  3. Remove recipients or attachments.

    You can remove added recipients and attachments. In both cases, all recipients or attachments are removed at once. It is not possible to remove one selected item. As all functions from the Email API, the email_remove_all_attachments() and email_remove_all_recipients() functions inform about success or failure by the returned error code:

    error_code = email_remove_all_recipients(msg);
    if (error_code != EMAILS_ERROR_NONE) 
    {
       dlog_print(DLOG_INFO, LOG_TAG, "Failed to add remove recipients\n");
    }
    error_code = email_remove_all_attachments (msg);
    if (error_code != EMAILS_ERROR_NONE) 
    {
       dlog_print(DLOG_INFO, LOG_TAG, "Failed to remove attachments\n");
    }
  4. Save the email before sending it.
    error_code = email_save_message(msg);
    if (error_code != EMAILS_ERROR_NONE) 
    {
       dlog_print(DLOG_INFO, LOG_TAG, "Failed to save email\n");
    }
    
  5. Define the email sending status callback.

    Email sending is an asynchronous operation, and thus the sending status cannot be checked directly in the return code from the email_send_message() function. To receive notifications about sending success or failure, a callback function must be defined:

    static void email_send_status(email_h email, email_sending_e result, void *user_data) 
    {
       if (result == EMAIL_SENDING_FAILED) 
       {
          // Error handling
          dlog_print(DLOG_INFO, LOG_TAG, "Failed to send email\n");
       }
       else if (result == EMAIL_SENDING_SUCCEEDED) 
       {
          // Sending was successful
          dlog_print(DLOG_INFO, LOG_TAG, "Email sending finished with success\n");
       }
    }
  6. Send the email.

    If the email message object is ready and the sending status callback is defined, the message can be sent:

    error_code = email_set_message_sent_cb(msg, email_send_status, NULL);
    if (error_code != EMAILS_ERROR_NONE) 
    {
       dlog_print(DLOG_INFO, LOG_TAG, "Failed to set sending status callback\n");
    }
    
    error_code = email_send_message(msg, false);
    if (error_code != EMAILS_ERROR_NONE) 
    {
       dlog_print(DLOG_INFO, LOG_TAG, "");
    }

    When the message is sent or if sending was canceled and the message is no longer needed, delete it using the email_destroy_message() function. The callback registered for the specified message must also be unset using the email_unset_message_sent_cb() callback function:

    error_code = email_unset_message_sent_cb(msg);
    if (error_code != EMAILS_ERROR_NONE) 
    {
       dlog_print(DLOG_INFO, LOG_TAG, "Failed to unset status callback\n");
    }
    
    error_code = email_destroy_message(msg);
    if (error_code != EMAILS_ERROR_NONE) 
    {
       dlog_print(DLOG_INFO, LOG_TAG, "Failed to delete email message\n");
    }
Go to top