Demonstration of Fastmail.com Application Programming Interface (API) utilizing the JSON Meta Application Protocol (JMAP) specification. This project provides a comprehensive guide on how to interact with Fastmail's API, enabling efficient email management through a simple command-line interface.

JMAP Specification

For a detailed understanding of the JMAP protocol, refer to the official specification: JMAP Specification

Generating a Fastmail API Security Token

To begin using the Fastmail API, you need to generate a security token:

1. Go to Fastmail Security Tokens.
2. Input a name (e.g., "demo-fastmail-jmap") in the "Name" field.
3. Select "Email Submission" in the "Scope" area.

After completion, your security token will look like:

fmu1-7c178287-1216c9163795fbefa9702c67571fcc32-0-172da3367b9fc53968fdb1e358e16747

You can then export this token to your shell for convenience:

export token="fmu1-7c178287-1216c9163795fbefa9702c67571fcc32-0-172da3367b9fc53968fdb1e358e16747"

Obtaining Your Session Account ID

Use the following command to acquire your session account ID:

curl --silent \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "Authorization: Bearer '$token'" \
  'https://api.fastmail.com/jmap/session' \

The typical output returns relevant URLs and account information in JSON format, including your account ID, which is essential for many API methods.

Making JMAP Requests

An example of a typical JMAP request:

{
  "using": [
    "urn:ietf:params:jmap:core",
    "urn:ietf:params:jmap:mail"
  ],
  "methodCalls": [
    [
      "Mailbox/get",
      { "accountId": "u00000000" },
      ""
    ]
  ]
}

Sending Emails via the Fastmail API

This project guides you through sending emails using the Fastmail API by employing the following methods:

1. Email/set - Create a draft of the email.
2. EmailSubmission/set - Send the email.

Example command to send an email:

curl \
--header 'Content-Type: application/json; charset=utf-8' \
--header 'Authorization: Bearer '$token' \
--request POST \
--data '{ ... }' \
'https://api.fastmail.com/jmap/api/'

This process sets up your email in the drafts folder before it's sent, ensuring all necessary parameters are correctly established.

Advanced Features

This repository also offers command examples for querying mailboxes, managing identities, and effectively parsing API responses using tools like jq, making it a versatile solution for developers looking to integrate Fastmail's robust emailing capabilities into their applications.

Explore the source code in the project to see practical implementations, and start leveraging the capabilities of the Fastmail API with JMAP for efficient email management!