Home / Masked Email

Masked Email

A Masked Email is an email address (alias) that is owned by a user (unlike regular aliases which are owned by a customer) and always target the owner user only.

Additional spec users

Masked Email addresses are available to JMAP and OAuth clients using the https://www.fastmail.com/dev/maskedemail capability/scope.

Description

Each MaskedEmail object contains a number of metadata fields: createdBy, forDomain, url and description. Make sure you set these correctly so the Fastmail user interface and other products all interoperate.

The createdBy property will be set by the server to the name of the client that created this masked email address. This depends on the authentication method used (oauth client, api token, web interface, etc). Your product should not try to set this. Example: “YourIntegration”

If your product is a password manager, the forDomain property should be the protocol and domain (i.e. origin) of the site the user is using the masked email for. It should not include any path or other components. Example: https://www.example.com

If your product supports deep links, the url property should be a deep link to the credential or other record related to this masked email address in your product. If deep links are not supported, leave this null. Do not set this to the domain of the site the user is using the masked email for, see above and use forDomain for this.

The description property should only be set to a short user supplied description of what this masked email address is for. If the user did not supply a description, leave it as the empty string. Do not set this to the name of your product, see createdBy above which is used for this. Do not set this to the domain of the site the user is using the masked email for, see above and use forDomain for this.

Object

A MaskedEmail object has the following properties:

  • id: String (immutable; server-set) The id of the Masked Email.
  • 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.
    • 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 protocol and domain (i.e. origin) of the site the user is using the masked email for. Example: https://www.example.com
  • description: String A short user-supplied description of what this masked email address is for. If the user did not supply a description, leave it as the empty string. 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 masked email address. This depends on the authentication method used (oauth client, api token, web interface, etc). Example: “YourIntegration”
  • url: String|null A deep link to the credential or other record related to this masked email address in your product. If deep links are not supported, leave this null.
  • 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).

The target of a Masked Email address is always the user to which it belongs.

MaskedEmail/get

Standard /get method. The ids argument may be null to fetch all at once.

MaskedEmail/set

Standard /set method. Only Masked Email addresses that have not received email may be destroyed.

If the user is an unverified trial creates may be rejected with a forbidden error, with a “subType” of isUnverifiedUser.

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.

A standard JMAP rateLimit error will be returned on create if a rate limit is violated.