If you find any errors, typos or have general feedback, select the text and click CTRL+ALT+ENTER.

What are we going to build?

In this tutorial, you’ll learn how to send email from your mobile app via SendGrid, a wonderful cloud service that provides a REST API for sending out emails.

The plugin demonstrates:

  • Sending an email using SendGrid API
  • Taking a picture and sending it as an attachment in the email
    • To take a picture you need to run the app on the device or use the Appery.io Tester app
    • When running in the browser, a sample attachment image will be sent (created in Javascript)

This is how the app from the plugin looks running on an Android device:
Screenshot (Apr 30, 2015 4-02-04 PM)

Before you begin

Tutorial level: intermediate.

Before being able to send out emails with SendGrid, you’ll need to sign up for an account. SendGrid offers a free plan.

Video

Watch a video that shows how to import, configure and test the plugin.

Creating a new app

  1. Sign into Appery.io and from Apps tab click “Create new app,” enter an app name, and click “Create.”
  2. Once the app builder loads, on the left-hand side, click Pages > startScreen – an editor with an blank startScreen will open:001-StartScreen

With a new app created, you are now ready to add the SendGrid plugin.

Importing the plugin

  1. To import the plugin, click Create New > From Plug-in:
    002-CreateNew_FromPlugin
  2. In the Communication category, you’ll see the “SendGrid Mail API”:
    003-SendgridMailAPIplugin
  3. Click “Import selected plugins.”
    • You’ll be asked whether you want to set the start page. Go ahead and select mail page. You always change the start page by going to Project > App settings > General.
  4. This step is optional but you can also change the theme used in this app.
    1. Go to  Project > App settings > General
    2. For Theme select material-design
  5. Open Pages > mail page. The page will look like this (using the material-design theme):
    SendGrid page

Next you are going to configure the SendGrid service.

Setting up secure proxy

When you sign up for SendGrid account you get a user name and API key (your password) to use when invoking the API. It’s a good idea to keep this sensitive information on the server as if someone gains access to this information, they will be able to send emails using your account. The secure proxy will protect this information so it’s never visible in the client.

Creating a database

The first step to creating a secure proxy is to create a database that will store the user name and password.

  1. From the app builder, click “Database” (upper right corner) or go to http://appery.io/database
  2. Click “Create new database”. For database name enter: SendGridDB. Click “Create”.
  3. Now you need to create a new collection. Click “Create new collection”. Name the collection Credentials.
  4. Click “+Col” to create a new column. Name the column: key
  5. Create another column and name it: keyValue.
  6. Now you are going to enter the SendGrid keys into the database.
    • Click “+Row” and enter api_user_proxy and its value (that’s your username)
    • Repeat the same for the api_key. Click “+Row” and enter api_key_proxy and its value (that’s your password). Your collection should look like this:
      Screen Shot 2015-04-30 at 3.28.06 PM

This data is now secure. Next you are going to setup the proxy to use the information in this collection.

Creating a secure proxy

  1. Click on “Secure Proxy” tab or go to http://appery.io/proxy
  2. Click “Create new proxy”, name the proxy SendGridProxy. Click “Create”.
  3. In the proxy setting page check “Use proxy + store sensitive (private) data in database”.
  4. For “Database” select SendGridDB.
  5. For “Collection” select Credentials.
  6. For “Key column” select key and for “Value column” select keyValue.
  7. Click “Save”.

The last step is configure the service to use this proxy.

Configuring the SendGrid API

The plugin has one service SendGrid_Mail to send email, there are just a few things you need to configure.

  1. Inside the App Builder, open Services > SendGrid_Mail service.
  2. For “Use Appery.io proxy”, click the refresh button to load the new proxy you just created and select it (SendGridProxy).
  3. Switch to “Request” tab. This tab contains all the service request parameters. You will also notice that the service will be getting the “api_user” and “api_key” from the proxy. The one request parameter you need to set is “from”. This is your from email.

The Request tab looks like this:

Screen Shot 2015-04-30 at 3.34.32 PM

  • api_key – SendGrid API key (your password). Saved in Appery.io database for security
  • api_user – SendGrid user name. Saved in Appery.io database for security
  • to – to email
  • toname (optional) – to name
  • from – from email
  • fromname (optional) – from name
  • subject – email subject
  • text – email text

You can modify the service and add more request parameters supported by the SendGrid Mail API.

Besides “from” (and optional “toname” and “fromname”) you don’t need to set the values in the service as they will be mapped from the page. This is how the mapping looks on the page (mail page > Data > sendgrid_email service > Before send mapping):

Screen Shot 2015-04-30 at 3.42.51 PM

More plugin details

More details about the plugin, how it works, and how you can remove the option to send attachments.

The service (SendGrid_Mail) is configured to send an attachment in the email. Because of that service’s “Request Content Type” is set to “Data”. The parameters such as to: email are defined in Request > Query String tab.

The actual file transfer (upload) is done via the browser’s FormData API.

When the “Send” button is clicked, the following code is invoked:

The first parameter is the SendGrid service instance name (defined in Data tab) and the second parameter is a reference to the image in base64 format. If you don’t upload an image, a sample image defined in JavaScript > SampleImageScript will be emailed.

The actual code that uploads the file is in JavaScript > FileUpload.

Testing the app

Now that the plugins is configured, you can test the app.

  1. Click the “Test” button to launch the app in the browser.
    • If you test the app in the browser, you can’t invoke the camera. You can still send a message, a sample image created in Project > JavaScript > SampleImageScript will be sent instead
    • To use the camera, use the Appery.io Tester app or install the app on a device

Testing the app on device after taking a picture:

Screenshot (Apr 30, 2015 4-02-04 PM)

Sending email without attachment

If you won’t need to send an attachment, you can easily modify the service to do that.

  1. Select “Send” button and open the JavaScript code in “Events” tab.
  2. You will see the following code:
  3. Comment the line that sends an email with an attachment and uncomment the line that sends the email without an attachment.

You can now test the app by sending an email without an attachment.