Skip to content
A Gmail API client for Elixir
Branch: master
Clone or download
Latest commit 4c44fbc May 24, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
config Bug fixes and config cleanup Dec 6, 2016
lib Fix default. Mar 21, 2017
test Add a test. Mar 21, 2017
.credo.exs Fix warning in Elixir 1.4. Mar 21, 2017
.gitignore Bug fixes and config cleanup Dec 6, 2016
.travis.yml Initial implementation Jul 26, 2016
LICENSE fixes Mar 4, 2016 bumped version Sep 13, 2016
mix.exs bump version May 24, 2018
mix.lock Dependencies updated May 24, 2018


Build Status Coverage Status version downloads Inline docs

A simple Gmail REST API client for Elixir.

You can find the hex package here, and the docs here.

You can find documentation for Gmail's API at


First, add the client to your mix.exs dependencies:

def deps do
  [{:gmail, "~> 0.1"}]

Then run $ mix do deps.get, compile to download and compile your dependencies.

Finally, add the :gmail application as your list of applications in mix.exs:

def application do
  [applications: [:logger, :gmail]]

Before you can work with mail for a user you'll need to start a process for them.

{:ok, pid} = Gmail.User.start_mail("", "user-refresh-token")

When a user process starts it will automatically fetch a new access token for that user. Then you can start playing with mail:

# fetch a list of threads
{:ok, threads, next_page_token} = Gmail.User.threads("")

# fetch the next page of threads using a page token
{:ok, _, _} = Gmail.User.threads("", %{page_token: next_page_token})

# fetch a thread by ID
{:ok, thread} = Gmail.User.thread("", "1233454566")

# fetch a list of labels
{:ok, labels} = Gmail.User.labels("")

Check the docs for a more complete list of functionality.

API Support

  • Threads
    • get
    • list
    • modify
    • delete
    • trash
    • untrash
  • Messages
    • delete
    • get
    • insert
    • list
    • modify
    • send
    • trash
    • untrash
    • import
    • batchDelete
  • Labels
    • create
    • delete
    • list
    • update
    • get
    • update
    • patch
  • Drafts
    • list
    • get
    • delete
    • update
    • create
    • send
    • send (with upload)
  • History
    • list
  • Attachments
    • get (thanks to @killtheliterate)


As of now the library doesn't do the initial auth generation for you; you'll need to create an app on the Google Developer Console to get a client ID and secret and authorize a user to get an authorization code, which you can trade for an access token.

The library will however, when you supply a refresh token, use that to refresh an expired access token for you. Take a look in the dev.exs.sample config file to see what your config should look like.


  • Stop mocking HTTP requests and use Bypass instead
  • Add format option when fetching threads
  • .. and messages
  • .. and drafts
  • Batched requests
  • Document the config (specifically pool size)
You can’t perform that action at this time.