cURL up with Nylas APIs for email, calendars, and contacts

cURL up with Nylas APIs for email, calendars, and contacts

With the help of cURL we can access the Nylas APIs in a fast and easy way. We only need a terminal and our Nylas credentials.


While Nylas offers awesome SDKs for Python, Node.js, Java, and Ruby, sometimes it’s good to learn Nylas by using cURL to make API calls. cURL—short for Client URL—is a command-line tool that lets you transfer data to and from a server with a variety of protocols. Many developers consider cURL to be simple to use and helpful for easily consuming new APIs; plus, it’s almost language agnostic so we can apply the concepts used in cURL to most language environments.

In this blog post, we’re going to see how to do the following:

  • Send emails with and without attachments
  • Read our inbox
  • Create a calendar and an event
  • Read and update contacts

Let’s jump in!

Getting started

The first thing we need to do is go to our Nylas Dashboard, and select Playground

Nylas Dashboard Sidebar

We can also press Ctrl+K and type Playground on the search bar.

Nylas Playground

We can choose from some templates to help us get started.

Nylas Playground Options

Let’s start with Send email.

Working with email

The first option, Send email, is selected by default:

Send Email

When we input our Access Token, we’re ready to send the email by pressing the green Run button:

Send Email Playground

If the cURL command was successful, we’ll get a JSON success response like this:

Send Email Terminal

We can also verify success in our email account:

Email verification

While we are in the Playground, we cannot change the content of the cURL command. However, we can copy everything and run it in our own local terminal, where we can for sure do some modifications:

Email Send using cURL

Just like we saw above, we will get a success confirmation in our terminal that our email has been sent:

Email confirmation

We can see that the email was sent from our account and not from a Nylas server:

Email Confirmation on client

You may be wondering by now… no attachments? I cannot send a funny picture? Well, of course you can! Read on to see how to do it.

Working with email and attachments

To send an attachment, we need to work with the Nylas files endpoint. In the terminal, go to the folder where your attachment resides and type the following cURL command:

curl --request POST \
  --url https://api.nylas.com/files \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'content-type: multipart/form-data; boundary=---011000010111000001101001' \
  --form '[email protected]<PATH_TO_FILE>'
Upload image

Now, it is very important that we copy the id returned, as we’re going to use it to add the file to our email.

We can copy the playground example we saw above and modify it accordingly:

curl -X POST \
'https://api.nylas.com/send' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache' \
--data-raw '{
  "subject": "From Nylas",
  "to": [
    {
      "email": "<EMAIL_TO>",
      "name": "blag "
    }
  ],
  "from": [
    {
      "email": "<EMAIL_FROM>",
      "name": "blag.nylas "
    }
  ],
  "body": "This email with attachment was sent using the Nylas email API. Visit https://nylas.com for details.",
"file_ids": [
    "<FILE_ID>"
  ]
}'

Now we paste the command into the terminal:

Send email with attachment

We will receive a confirmation back:

Confirmation for Email with Attachment

And then we can simply check on our target email account:

Check attachment from client

We’ve sent an email with an attachment using cURL! What else can we do?

Reading our Inbox

We can also take a look at our inbox messages. In the Nylas Dashboard, select the “See conversation history” button:

Conversation history

Just like we did before, we can copy this code and run it in the terminal, with the option of changing some of the parameters. For example, we can use in=inbox as a query parameter in the URL to read exclusively from our inbox folder. Or we can use has_attachment=true to display only email containing attachments

Or we can use both query parameters together:

curl -X GET \
'https://api.nylas.com/messages?limit=5&view=expanded&in=inbox&has_attachment=true' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'

We’ll get back—you guessed it—all emails from our inbox that have an attachment:

Read inbox

Nylas can do all kinds of great stuff with email, but it goes even deeper than that. Let’s turn our focus to using Nylas and cURL to work with calendars.

Working with Calendars

Back in the Nylas Dashboard Playground, let’s select See upcoming events. This cURL call will grab all the events happening one year into the future after the specified date (dates are specified as Unix timestamps):

Calendar Playground

But that’s not very helpful as by default it’s taking the auto-generated calendar. Let’s target a calendar created by us.

In our local terminal window, let’s run this cURL command which gets a list of all calendars in our connected account:

curl --request GET \
  --url 'https://api.nylas.com/calendars' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json'

Grab any calendar ID that you’d like to query:

Get Calendars

We’ll use that calendar ID in our next cURL call:

curl -X GET \
--url 'https://api.nylas.com/events?calendar_id=<CALENDAR_ID>&starts_after=1644559200' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json'

Now we get back all of the events on the chosen calendar that start after the date we specified in the cURL call:

Read Calendar events

To wrap up, let’s have a look at using Nylas and cURL to work with contacts.

Working with Contacts

Working with contacts is important for many applications, such as CRMs. Using cURL to call Nylas Contacts API is a great way to get started.

For example, if we want to get a list of our contacts, we can make a GET request to Nylas using cURL:

curl --request GET \
  --url https://api.nylas.com/contacts \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json

As you might expect, this returns a full list of all of our contacts:

Get contacts

We might have a lot of contacts in the list, especially because every time we get an email from someone new, an auto-generated contact will be added. So, let’s try looking someone up:

curl --request GET \
  --url 'https://api.nylas.com/contacts?email=alvaro.t%40nylas.com' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json'

As we can see in the example, we’re searching using a query parameter in the URL. In this case, we’re searching for [email protected]; however, we’re using alvaro.t%40nylas.com … if you’re wondering why the %40: it’s just because we need to use percent-encoding (URL encoding) for all parameter values.

Running the command above, here’s what you’ll get (assuming that I’m one of your contacts!):

Find contact

Now let’s say that we want to get the picture of the contact. First, grab the ID of the contact returned above, then add it to the following cURL command:

curl --request GET \
  --url https://api.nylas.com/contacts/<ID>/picture \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' > picture.jpg

cURL will download the image for you:

Download and visualize contact photo

Once downloaded, we can use the open command to display the picture: $ open <image-filenmame>.

And now you can cURL up with Nylas!

I hope you liked working with cURL and the Nylas APIs. We have now learned how to work with emails, add attachments, look at our calendar events, and retrieve details about one of our contacts. If you want more information, please go to our documentation.

You May Also Like

Working with the Nylas Contacts API and Python
Super power the Nylas CLI with Fig
CRM workflow automation
How to Streamline Communication Workflows and Integrate Automation Into Your CRM