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

  Initialize the email service for use.

• Creating and Sending Email Messages

  Create and send a message after adding attachments and recipients.

Initializing the Email Service

To initialize the email service for use:

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

   #include <email.h>
   

   To ensure that an Email function has been executed properly, make sure that the return value is equal to EMAILS_ERROR_NONE.

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 Messages

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.

   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");
   }
   

   The function return code defines whether the message creation succeeded. The EMAIL_ERROR_ACCOUNT_NOT_FOUND error is not related to the email service as such; it occurs if no email account has been configured on the device.

2. Manage recipients and attachments:

   1. Add recipients to the email message one by one. You cannot add lists of recipients in one function call. Each address must be given as a character string with the address type (TO, CC, BCC) 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");
      }
      

   2. Add an attachment to the email message with 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.

      In both cases, all recipients or attachments are removed at once. It is not possible to remove one selected item.

      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");
      }
      

3. 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");
   }
   

4. Define and register 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, use a callback function.

   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");
      }
   }
   
   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");
   }
   

5. Send the email:

   error_code = email_send_message(msg, false);
   if (error_code != EMAILS_ERROR_NONE) 
   {
      dlog_print(DLOG_INFO, LOG_TAG, "");
   }
   

6. When the message is sent or if sending is canceled and the message no longer needed, delete it using the email_destroy_message() function. The registered email sending status callback must also be unset using the email_unset_message_sent_cb() 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");
   }