### JMAP Session Resource Source: https://www.fastmail.com/dev To start using the JMAP API, you need the URL of the JMAP Session resource. This resource provides information necessary to interact with the JMAP API. ```APIDOC ## JMAP Session Resource ### Description The JMAP session resource provides the endpoint for interacting with the JMAP API and obtaining necessary session information. ### Endpoint `https://api.fastmail.com/jmap/session` ### Authentication Requires an API token. Add an `Authorization` header set to `Bearer {value}`, where `{value}` is the API token. ### CORS Enabled JMAP APIs are CORS enabled, allowing integrations directly from web applications. ``` -------------------------------- ### Getting a new access token using a refresh token Source: https://www.fastmail.com/dev When an access token expires (resulting in a 401 response), clients can obtain a new one by making a POST request to the token endpoint with grant_type set to "refresh_token" and providing the existing refresh_token. ```APIDOC ## POST https://api.fastmail.com/oauth/refresh ### Description Obtain a new access token using a valid refresh token. ### Method POST ### Endpoint https://api.fastmail.com/oauth/refresh ### Parameters #### Request Body - **client_id** (string) - Required - The client ID for the application. - **grant_type** (string) - Required - Must be "refresh_token". - **refresh_token** (string) - Required - The refresh token obtained previously. ### Response #### Success Response (200 OK) - **access_token** (string) - A bearer token for authenticating API requests. - **token_type** (string) - The type of the access token (e.g., "bearer"). - **expires_in** (number) - The lifetime in seconds of the access token. - **scope** (string) - The space-delimited set of scopes. - **refresh_token** (string) - A new refresh token that MUST replace the previous one. #### Response Example ```json { "access_token": "NEW_ACCESS_TOKEN", "token_type": "bearer", "expires_in": 3600, "scope": "read write", "refresh_token": "NEW_REFRESH_TOKEN" } ``` #### Error Response (400 Bad Request) - **error** (string) - A single ASCII error code indicating why the request failed. - **error_description** (string) - Optional - A user-readable explanation of the error. - **temporary** (boolean) - Optional - Indicates if the refresh token might become valid again. ``` -------------------------------- ### Obtaining an initial refresh token Source: https://www.fastmail.com/dev Clients obtain initial refresh and access tokens by making a POST request to the Fastmail token endpoint. The request must include client_id, redirect_uri, grant_type (set to "authorization_code"), code, and code_verifier. ```APIDOC ## POST https://api.fastmail.com/oauth/refresh ### Description Obtain initial refresh and access tokens after user authorization. ### Method POST ### Endpoint https://api.fastmail.com/oauth/refresh ### Parameters #### Request Body - **client_id** (string) - Required - The client ID for the application. - **redirect_uri** (string) - Required - The redirect URI sent with the authorization request. - **grant_type** (string) - Required - Must be "authorization_code". - **code** (string) - Required - The authorization code received via redirect. - **code_verifier** (string) - Required - The code verifier generated for the authorization. ### Response #### Success Response (200 OK) - **access_token** (string) - A bearer token for authenticating API requests. - **token_type** (string) - The type of the access token (e.g., "bearer"). - **expires_in** (number) - The lifetime in seconds of the access token. - **scope** (string) - The space-delimited set of scopes. - **refresh_token** (string) - The refresh token for obtaining new access tokens. #### Response Example ```json { "access_token": "YOUR_ACCESS_TOKEN", "token_type": "bearer", "expires_in": 3600, "scope": "read write", "refresh_token": "YOUR_REFRESH_TOKEN" } ``` #### Error Response (400 Bad Request) - **error** (string) - A single ASCII error code indicating why the request failed. ``` -------------------------------- ### OAuth Authorization URL Source: https://www.fastmail.com/dev Clients initiate authorization by opening the user’s web browser at the Fastmail OAuth Authorization URL. Specific URL parameters are required for a successful request. ```APIDOC ## GET /oauth/authorize ### Description Initiates the OAuth authorization flow by directing the user's browser to the Fastmail authorization endpoint. ### Method GET ### Endpoint https://api.fastmail.com/oauth/authorize ### Parameters #### Query Parameters - **client_id** (string) - Required - The client ID for the application. - **redirect_uri** (string) - Required - One of the registered redirect URIs for the application. - **response_type** (string) - Required - Must be "code". - **scope** (string) - Required - A space-delimited set of scopes the client requests. - **code_challenge** (string) - Required - A PKCE code challenge (SHA-256 hashed and Base64URL encoded). - **code_challenge_method** (string) - Required - Must be "S256". - **state** (string) - Required - An opaque value used to maintain state between the request and callback. ### Response #### Success Response (Redirect) Upon successful authorization, the user agent is redirected to the `redirect_uri` with the following query parameters: - **code** (string) - The authorization code, valid for 10 minutes. - **state** (string) - The value of the state parameter passed in the request. #### Error Response (Redirect) If authorization fails, the user agent may be redirected with error parameters: - **error** (string) - An error type as defined by RFC 6749. - **state** (string) - The value of the state parameter passed in the request. ``` -------------------------------- ### MaskedEmail/set Source: https://www.fastmail.com/dev Creates or updates MaskedEmail objects. The server generates the email address based on domain settings and provided emailPrefix, or a random prefix if none is supplied. ```APIDOC ## MaskedEmail/set This is a standard “/set” method as described in RFC8620, Section 5.3. The email address will be generated by the server as follows: 1. The domain will be set as per the Masked Email domain setting for the customer to which the user belongs. 2. The mailbox will start with the given “emailPrefix” if provided, otherwise, the server will generate a random one from a predefined corpus. To prevent abuse, there are rate limits in place. A standard JMAP `rateLimit` SetError will be returned on create if these are exceeded. ``` -------------------------------- ### OAuth Scopes Source: https://www.fastmail.com/dev Lists the supported OAuth 2.0 scopes for Fastmail API access, detailing the permissions granted by each scope. ```APIDOC ## OAuth at Fastmail Fastmail can authorize third-party clients to access a user’s data using OAuth 2.0, in conformance with the Authorization Code grant flow of the OAuth 2.0 Authorization Framework, as defined in RFC 6749. ### Scopes The following scopes are currently supported: **urn:ietf:params:jmap:core** This grants access to use the JMAP protocol and fetch the user’s session object. You MUST request this scope if requesting any other JMAP-based scope. **urn:ietf:params:jmap:mail** This represents support for the Mailbox, Thread, Email, and SearchSnippet data types and associated API methods. This is the scope you need to read and manage mail for a user. Full documentation is in RFC8621. **urn:ietf:params:jmap:submission** This represents support for the Identity and EmailSubmission data types and associated API methods. You will need this scope if you want to send mail for a user via JMAP. Full documentation is in RFC8621. **urn:ietf:params:jmap:vacationresponse** This represents support for the VacationResponse data type and associated API methods. With this scope, you can change the user’s vacation response and turn it on or off. **urn:ietf:params:jmap:contacts** This represents support for the AddressBook and ContactCard data types and associated API methods. You will need this scope if you want to read and manage a user’s contacts. Full documentation is in RFC9610. **https://www.fastmail.com/dev/maskedemail** This grants the ability to read and write the MaskedEmail data type, as documented above. ``` -------------------------------- ### MaskedEmail/get Source: https://www.fastmail.com/dev Retrieves one or more MaskedEmail objects. The 'ids' argument can be null to fetch all masked emails. ```APIDOC ## MaskedEmail/get This is a standard “/get” method as described in RFC8620, Section 5.1. The “ids” argument may be `null` to fetch all at once. ``` -------------------------------- ### Masked Email API Source: https://www.fastmail.com/dev The Masked Email API is a JMAP extension that allows applications to manage a user's Masked Email addresses. It supports specific metadata fields for each MaskedEmail object. ```APIDOC ## Masked Email API ### Description This API allows management of Masked Email addresses through a JMAP extension. It defines metadata fields such as `createdBy`, `forDomain`, `url`, and `description`. ### Capability `https://www.fastmail.com/dev/maskedemail` ### MaskedEmail Object Fields - **createdBy** (string) - Set by the server, indicates the client that created the masked email. Do not attempt to set this field. - **forDomain** (string) - If your product is a password manager, set this to the protocol and domain (origin) of the site the masked email is for (e.g., `https://www.example.com`). Do not include paths. - **url** (string | null) - If your product supports deep links, set this to a deep link for the associated credential or record. Leave as `null` if not supported. Do not set this to the site's domain. - **description** (string) - A short, user-supplied description of the masked email's purpose. Leave as an empty string if no description is provided. Do not set this to your product name or the site's domain. ``` -------------------------------- ### Revoking a token Source: https://www.fastmail.com/dev Clients can revoke all associated access and refresh tokens by making an authenticated POST request to the revoke endpoint. ```APIDOC ## POST https://api.fastmail.com/oauth/revoke ### Description Revoke all associated access and refresh tokens for the client. ### Method POST ### Endpoint https://api.fastmail.com/oauth/revoke ### Parameters (Authentication details not specified in source, assumed to be handled via standard means like Authorization header) ### Response (Success and error response details not specified in source, assumed to be standard HTTP responses.) ``` -------------------------------- ### MaskedEmail Data Type Source: https://www.fastmail.com/dev Defines the properties of the MaskedEmail data type, including its fields, types, and constraints. ```APIDOC ## MaskedEmail Data Type This capability adds support for a new MaskedEmail data type, with the following properties: * **id** : `String` (immutable; server-set) The id of the masked email address. * **email** : `String` (immutable; server-set) The email address. * **state** : `String` (default: pending) This MUST be one of: * `pending`: the initial state. Once set to anything else, it cannot be set back to pending. If a message is received by an address in the “pending” state, it will automatically be converted to “enabled”. **Pending email addresses are automatically deleted 24h after creation and are not shown in the Fastmail UI.** * `enabled`: the address is active and receiving mail normally. * `disabled`: the address is active, but mail is sent straight to trash. * `deleted`: the address is inactive; any mail sent to the address is bounced. * **forDomain** : `String` The domain name of the site this address was created for, e.g. “https://example.com”. This is intended to be added automatically by password managers. * **description** : `String` A short description of what this email address is for. This will be displayed next to the email to help users identify it, and also be used to tag mail sent to it. * **lastMessageAt** : `UTCDate|null` (server-set) The date-time the most recent message was received at this email address, if any. * **createdAt** : `UTCDate` (immutable; server-set) The date-time the email address was created. * **createdBy** : `String` (immutable; server-set) The name of the client that created this email address. This will be set by the server automatically based on the credentials used to authenticate the request, e.g. “ACME Password Manager”. * **url** : `String|null` A URL pointing back to the integrator’s use of this email address, e.g. a custom-uri to open “ACME Password Manager” at the appropriate entry. * **emailPrefix** : `String` (create-only) This is only used on create and otherwise ignored; it is not returned when MaskedEmail objects are fetched. If supplied, the server-assigned email will start with the given prefix. The string MUST be <= 64 characters in length and MUST only contain characters a-z, 0-9 and _ (underscore). ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.