CINXE.COM

<!doctype html><html lang="en" class="no-script"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><link rel="preload" as="font" type="font/woff2" href="/assets/fonts/roca/rocaone-rg-webfont.woff2" crossorigin><link rel="preload" as="font" type="font/woff2" href="/assets/fonts/proximanova/basic/proximanova-regular.woff2" crossorigin><link rel="preload" as="font" type="font/woff2" href="/assets/fonts/proximanova/basic/proximanova-semibold.woff2" crossorigin><link rel="preload" as="font" type="font/woff2" href="/assets/fonts/proximanova/basic/proximanova-bold.woff2" crossorigin><title>API Documentation | Fastmail</title><meta property="og:title" content="API Documentation"><meta name="twitter:title" content="API Documentation"><link rel="canonical" href="https://www.fastmail.com/dev/"><meta property="og:url" content="https://www.fastmail.com/dev/"><meta property="og:site_name" content="Fastmail"><meta name="twitter:site" content="@Fastmail"><meta name="twitter:creator" content="@Fastmail"><meta property="og:image" content="https://www.fastmail.com/assets/images/opengraph/Fastmail-OG.png"><meta name="twitter:image" content="https://www.fastmail.com/assets/images/opengraph/Fastmail-OG.png"><meta property="og:image:type" content="png"><meta property="og:image:width" content="1200"><meta property="og:image:height" content="630"><meta name="twitter:card" content="summary_large_image"><meta property="og:type" content="website"><meta property="eleventy:path" content="./source/pages/dev.md"><script>document.querySelector("html").classList.remove("no-script");function run(o){document.readyState==="loading"?document.addEventListener("DOMContentLoaded",o):o()}(function(){if("fonts"in document){if(sessionStorage.fontsLoaded){document.documentElement.classList.add("fonts-loaded-2");return}Promise.all([document.fonts.load("400 1em 'Proxima Nova'"),document.fonts.load("400 1em roca")]).then(function(){document.documentElement.classList.add("fonts-loaded-1"),Promise.all([document.fonts.load("600 1em 'Proxima Nova'"),document.fonts.load("700 1em 'Proxima Nova'"),document.fonts.load("100 1em roca"),document.fonts.load("300 1em roca")]).then(function(){document.documentElement.classList.remove("fonts-loaded-1"),document.documentElement.classList.add("fonts-loaded-2"),sessionStorage.fontsLoaded=!0})})}})(); </script><style> /*! * Web Fonts from Fontspring.com * * All OpenType features and all extended glyphs have been removed. * Fully installable fonts can be purchased at http://www.fontspring.com * * The fonts included in this stylesheet are subject to the End User License you purchased * from Fontspring. The fonts are protected under domestic and international trademark and * copyright law. You are prohibited from modifying, reverse engineering, duplicating, or * distributing this font software. * * (c) 2010-2024 Fontspring * * The fonts included are copyrighted by the vendors listed below. * * Vendor: Mark Simonson Studio * License URL: https://www.fontspring.com/licenses/mark-simonson-studio/webfont * * Vendor: My Creative Land * License URL: https://www.fontspring.com/license/my-creative-land/webfont */@font-face{descent-override:55%;font-family:Georgia Roca Fallback;font-style:normal;size-adjust:90%;src:local(Georgia-Bold)}@font-face{font-display:swap;font-family:roca;font-style:normal;font-weight:100;src:url(/assets/fonts/roca/rocaone-th-webfont.woff2) format("woff2")}@font-face{font-display:swap;font-family:roca;font-style:normal;font-weight:300;src:url(/assets/fonts/roca/rocaone-lt-webfont.woff2) format("woff2")}@font-face{font-display:swap;font-family:roca;font-style:normal;font-weight:400;src:url(/assets/fonts/roca/rocaone-rg-webfont.woff2) format("woff2")}@font-face{font-display:swap;font-family:Proxima Nova;font-style:normal;font-weight:300;src:local("Proxima Nova Light"),local("ProximaNova-Light"),url(/assets/fonts/proximanova/basic/proximanova-light.woff2) format("woff2"),url(/assets/fonts/proximanova/basic/proximanova-light.woff) format("woff");unicode-range:u+0000-007e,u+00a0-00a3,u+00a5,u+00a8-00a9,u+00ab,u+00ae,u+00b4,u+00b8,u+00bb,u+00bf-00c2,u+00c4,u+00c6-00cb,u+00cd-00cf,u+00d1,u+00d3-00d4,u+00d6,u+00d9-00dc,u+00df-00e2,u+00e4,u+00e6-00eb,u+00ed-00ef,u+00f1,u+00f3-00f4,u+00f6,u+00f9-00fc,u+00ff,u+0152-0153,u+0178,u+02c6,u+02da,u+02dc,u+2013-2014,u+2018-201a,u+201c-201e,u+2022,u+2026,u+202f,u+2039-203a,u+20ac,u+2122}@font-face{font-display:swap;font-family:Proxima Nova;font-style:normal;font-weight:300;src:local("Proxima Nova Light"),local("ProximaNova-Light"),url(/assets/fonts/proximanova/extended/proximanova-light.woff2) format("woff2"),url(/assets/fonts/proximanova/extended/proximanova-light.woff) format("woff");unicode-range:u+007f-009f,u+00a4,u+00a6-00a7,u+00aa,u+00ac-00ad,u+00af-00b3,u+00b5-00b7,u+00b9-00ba,u+00bc-00be,u+00c3,u+00c5,u+00cc,u+00d0,u+00d2,u+00d5,u+00d7-00d8,u+00dd-00de,u+00e3,u+00e5,u+00ec,u+00f0,u+00f2,u+00f5,u+00f7-00f8,u+00fd-00fe,u+0100-0151,u+0154-0177,u+0179-02c5,u+02c7-02d9,u+02db,u+02dd-2012,u+2015-2017,u+201b,u+201f-2021,u+2023-2025,u+2027-202e,u+2030-2038,u+203b-20ab,u+20ad-2121,u+2123-fb04}@font-face{font-display:swap;font-family:Proxima Nova;font-style:normal;font-weight:400;src:local("Proxima Nova Regular"),local("ProximaNova-Regular"),url(/assets/fonts/proximanova/basic/proximanova-regular.woff2) format("woff2"),url(/assets/fonts/proximanova/basic/proximanova-regular.woff) format("woff");unicode-range:u+0000-007e,u+00a0-00a3,u+00a5,u+00a8-00a9,u+00ab,u+00ae,u+00b4,u+00b8,u+00bb,u+00bf-00c2,u+00c4,u+00c6-00cb,u+00cd-00cf,u+00d1,u+00d3-00d4,u+00d6,u+00d9-00dc,u+00df-00e2,u+00e4,u+00e6-00eb,u+00ed-00ef,u+00f1,u+00f3-00f4,u+00f6,u+00f9-00fc,u+00ff,u+0152-0153,u+0178,u+02c6,u+02da,u+02dc,u+2013-2014,u+2018-201a,u+201c-201e,u+2022,u+2026,u+202f,u+2039-203a,u+20ac,u+2122}@font-face{font-display:swap;font-family:Proxima Nova;font-style:normal;font-weight:400;src:local("Proxima Nova Regular"),local("ProximaNova-Regular"),url(/assets/fonts/proximanova/extended/proximanova-regular.woff2) format("woff2"),url(/assets/fonts/proximanova/extended/proximanova-regular.woff) format("woff");unicode-range:u+007f-009f,u+00a4,u+00a6-00a7,u+00aa,u+00ac-00ad,u+00af-00b3,u+00b5-00b7,u+00b9-00ba,u+00bc-00be,u+00c3,u+00c5,u+00cc,u+00d0,u+00d2,u+00d5,u+00d7-00d8,u+00dd-00de,u+00e3,u+00e5,u+00ec,u+00f0,u+00f2,u+00f5,u+00f7-00f8,u+00fd-00fe,u+0100-0151,u+0154-0177,u+0179-02c5,u+02c7-02d9,u+02db,u+02dd-2012,u+2015-2017,u+201b,u+201f-2021,u+2023-2025,u+2027-202e,u+2030-2038,u+203b-20ab,u+20ad-2121,u+2123-fb04}@font-face{font-display:swap;font-family:Proxima Nova;font-style:italic;font-weight:400;src:local("Proxima Nova Regular Italic"),local("ProximaNova-RegularIt"),url(/assets/fonts/proximanova/basic/proximanova-regularit.woff2) format("woff2"),url(/assets/fonts/proximanova/basic/proximanova-regularit.woff) format("woff");unicode-range:u+0000-007e,u+00a0-00a3,u+00a5,u+00a8-00a9,u+00ab,u+00ae,u+00b4,u+00b8,u+00bb,u+00bf-00c2,u+00c4,u+00c6-00cb,u+00cd-00cf,u+00d1,u+00d3-00d4,u+00d6,u+00d9-00dc,u+00df-00e2,u+00e4,u+00e6-00eb,u+00ed-00ef,u+00f1,u+00f3-00f4,u+00f6,u+00f9-00fc,u+00ff,u+0152-0153,u+0178,u+02c6,u+02da,u+02dc,u+2013-2014,u+2018-201a,u+201c-201e,u+2022,u+2026,u+202f,u+2039-203a,u+20ac,u+2122}@font-face{font-display:swap;font-family:Proxima Nova;font-style:italic;font-weight:400;src:local("Proxima Nova Regular Italic"),local("ProximaNova-RegularIt"),url(/assets/fonts/proximanova/extended/proximanova-regularit.woff2) format("woff2"),url(/assets/fonts/proximanova/extended/proximanova-regularit.woff) format("woff");unicode-range:u+007f-009f,u+00a4,u+00a6-00a7,u+00aa,u+00ac-00ad,u+00af-00b3,u+00b5-00b7,u+00b9-00ba,u+00bc-00be,u+00c3,u+00c5,u+00cc,u+00d0,u+00d2,u+00d5,u+00d7-00d8,u+00dd-00de,u+00e3,u+00e5,u+00ec,u+00f0,u+00f2,u+00f5,u+00f7-00f8,u+00fd-00fe,u+0100-0151,u+0154-0177,u+0179-02c5,u+02c7-02d9,u+02db,u+02dd-2012,u+2015-2017,u+201b,u+201f-2021,u+2023-2025,u+2027-202e,u+2030-2038,u+203b-20ab,u+20ad-2121,u+2123-fb04}@font-face{font-display:swap;font-family:Proxima Nova;font-style:normal;font-weight:500;src:local("Proxima Nova Medium"),local("ProximaNova-Medium"),url(/assets/fonts/proximanova/basic/proximanova-medium.woff2) format("woff2"),url(/assets/fonts/proximanova/basic/proximanova-medium.woff) format("woff");unicode-range:u+0000-007e,u+00a0-00a3,u+00a5,u+00a8-00a9,u+00ab,u+00ae,u+00b4,u+00b8,u+00bb,u+00bf-00c2,u+00c4,u+00c6-00cb,u+00cd-00cf,u+00d1,u+00d3-00d4,u+00d6,u+00d9-00dc,u+00df-00e2,u+00e4,u+00e6-00eb,u+00ed-00ef,u+00f1,u+00f3-00f4,u+00f6,u+00f9-00fc,u+00ff,u+0152-0153,u+0178,u+02c6,u+02da,u+02dc,u+2013-2014,u+2018-201a,u+201c-201e,u+2022,u+2026,u+202f,u+2039-203a,u+20ac,u+2122}@font-face{font-display:swap;font-family:Proxima Nova;font-style:normal;font-weight:500;src:local("Proxima Nova Medium"),local("ProximaNova-Medium"),url(/assets/fonts/proximanova/extended/proximanova-medium.woff2) format("woff2"),url(/assets/fonts/proximanova/extended/proximanova-medium.woff) format("woff");unicode-range:u+007f-009f,u+00a4,u+00a6-00a7,u+00aa,u+00ac-00ad,u+00af-00b3,u+00b5-00b7,u+00b9-00ba,u+00bc-00be,u+00c3,u+00c5,u+00cc,u+00d0,u+00d2,u+00d5,u+00d7-00d8,u+00dd-00de,u+00e3,u+00e5,u+00ec,u+00f0,u+00f2,u+00f5,u+00f7-00f8,u+00fd-00fe,u+0100-0151,u+0154-0177,u+0179-02c5,u+02c7-02d9,u+02db,u+02dd-2012,u+2015-2017,u+201b,u+201f-2021,u+2023-2025,u+2027-202e,u+2030-2038,u+203b-20ab,u+20ad-2121,u+2123-fb04}@font-face{font-display:swap;font-family:Proxima Nova;font-style:normal;font-weight:600;src:local("Proxima Nova Semibold"),local("ProximaNova-Semibold"),url(/assets/fonts/proximanova/basic/proximanova-semibold.woff2) format("woff2"),url(/assets/fonts/proximanova/basic/proximanova-semibold.woff) format("woff");unicode-range:u+0000-007e,u+00a0-00a3,u+00a5,u+00a8-00a9,u+00ab,u+00ae,u+00b4,u+00b8,u+00bb,u+00bf-00c2,u+00c4,u+00c6-00cb,u+00cd-00cf,u+00d1,u+00d3-00d4,u+00d6,u+00d9-00dc,u+00df-00e2,u+00e4,u+00e6-00eb,u+00ed-00ef,u+00f1,u+00f3-00f4,u+00f6,u+00f9-00fc,u+00ff,u+0152-0153,u+0178,u+02c6,u+02da,u+02dc,u+2013-2014,u+2018-201a,u+201c-201e,u+2022,u+2026,u+202f,u+2039-203a,u+20ac,u+2122}@font-face{font-display:swap;font-family:Proxima Nova;font-style:normal;font-weight:600;src:local("Proxima Nova Semibold"),local("ProximaNova-Semibold"),url(/assets/fonts/proximanova/extended/proximanova-semibold.woff2) format("woff2"),url(/assets/fonts/proximanova/extended/proximanova-semibold.woff) format("woff");unicode-range:u+007f-009f,u+00a4,u+00a6-00a7,u+00aa,u+00ac-00ad,u+00af-00b3,u+00b5-00b7,u+00b9-00ba,u+00bc-00be,u+00c3,u+00c5,u+00cc,u+00d0,u+00d2,u+00d5,u+00d7-00d8,u+00dd-00de,u+00e3,u+00e5,u+00ec,u+00f0,u+00f2,u+00f5,u+00f7-00f8,u+00fd-00fe,u+0100-0151,u+0154-0177,u+0179-02c5,u+02c7-02d9,u+02db,u+02dd-2012,u+2015-2017,u+201b,u+201f-2021,u+2023-2025,u+2027-202e,u+2030-2038,u+203b-20ab,u+20ad-2121,u+2123-fb04}@font-face{font-display:swap;font-family:Proxima Nova;font-style:normal;font-weight:700;src:local("Proxima Nova Bold"),local("ProximaNova-Bold"),url(/assets/fonts/proximanova/basic/proximanova-bold.woff2) format("woff2"),url(/assets/fonts/proximanova/basic/proximanova-bold.woff) format("woff");unicode-range:u+0000-007e,u+00a0-00a3,u+00a5,u+00a8-00a9,u+00ab,u+00ae,u+00b4,u+00b8,u+00bb,u+00bf-00c2,u+00c4,u+00c6-00cb,u+00cd-00cf,u+00d1,u+00d3-00d4,u+00d6,u+00d9-00dc,u+00df-00e2,u+00e4,u+00e6-00eb,u+00ed-00ef,u+00f1,u+00f3-00f4,u+00f6,u+00f9-00fc,u+00ff,u+0152-0153,u+0178,u+02c6,u+02da,u+02dc,u+2013-2014,u+2018-201a,u+201c-201e,u+2022,u+2026,u+202f,u+2039-203a,u+20ac,u+2122}@font-face{font-display:swap;font-family:Proxima Nova;font-style:normal;font-weight:700;src:local("Proxima Nova Bold"),local("ProximaNova-Bold"),url(/assets/fonts/proximanova/extended/proximanova-bold.woff2) format("woff2"),url(/assets/fonts/proximanova/extended/proximanova-bold.woff) format("woff");unicode-range:u+007f-009f,u+00a4,u+00a6-00a7,u+00aa,u+00ac-00ad,u+00af-00b3,u+00b5-00b7,u+00b9-00ba,u+00bc-00be,u+00c3,u+00c5,u+00cc,u+00d0,u+00d2,u+00d5,u+00d7-00d8,u+00dd-00de,u+00e3,u+00e5,u+00ec,u+00f0,u+00f2,u+00f5,u+00f7-00f8,u+00fd-00fe,u+0100-0151,u+0154-0177,u+0179-02c5,u+02c7-02d9,u+02db,u+02dd-2012,u+2015-2017,u+201b,u+201f-2021,u+2023-2025,u+2027-202e,u+2030-2038,u+203b-20ab,u+20ad-2121,u+2123-fb04}@font-face{font-display:swap;font-family:Proxima Nova;font-style:italic;font-weight:700;src:local("Proxima Nova Bold Italic"),local("ProximaNova-BoldIt"),url(/assets/fonts/proximanova/basic/proximanova-boldit.woff2) format("woff2"),url(/assets/fonts/proximanova/basic/proximanova-boldit.woff) format("woff");unicode-range:u+0000-007e,u+00a0-00a3,u+00a5,u+00a8-00a9,u+00ab,u+00ae,u+00b4,u+00b8,u+00bb,u+00bf-00c2,u+00c4,u+00c6-00cb,u+00cd-00cf,u+00d1,u+00d3-00d4,u+00d6,u+00d9-00dc,u+00df-00e2,u+00e4,u+00e6-00eb,u+00ed-00ef,u+00f1,u+00f3-00f4,u+00f6,u+00f9-00fc,u+00ff,u+0152-0153,u+0178,u+02c6,u+02da,u+02dc,u+2013-2014,u+2018-201a,u+201c-201e,u+2022,u+2026,u+202f,u+2039-203a,u+20ac,u+2122}@font-face{font-display:swap;font-family:Proxima Nova;font-style:italic;font-weight:700;src:local("Proxima Nova Bold Italic"),local("ProximaNova-BoldIt"),url(/assets/fonts/proximanova/extended/proximanova-boldit.woff2) format("woff2"),url(/assets/fonts/proximanova/extended/proximanova-boldit.woff) format("woff");unicode-range:u+007f-009f,u+00a4,u+00a6-00a7,u+00aa,u+00ac-00ad,u+00af-00b3,u+00b5-00b7,u+00b9-00ba,u+00bc-00be,u+00c3,u+00c5,u+00cc,u+00d0,u+00d2,u+00d5,u+00d7-00d8,u+00dd-00de,u+00e3,u+00e5,u+00ec,u+00f0,u+00f2,u+00f5,u+00f7-00f8,u+00fd-00fe,u+0100-0151,u+0154-0177,u+0179-02c5,u+02c7-02d9,u+02db,u+02dd-2012,u+2015-2017,u+201b,u+201f-2021,u+2023-2025,u+2027-202e,u+2030-2038,u+203b-20ab,u+20ad-2121,u+2123-fb04}</style><link rel="stylesheet" href="/assets/css/main-a7851194.css"><link rel="icon" href="/favicon.ico?v=64679438" sizes="48x48"><link rel="icon" href="/favicon.svg?v=5843ac65" sizes="any" type="image/svg+xml"><link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png?v=961604de"><link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png?v=10da1173"><link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png?v=79a96923"><link rel="manifest" href="/site.webmanifest?v=310b8694"><link rel="mask-icon" href="/safari-pinned-tab.svg?v=857521d6" color="#176bad"><meta name="msapplication-TileColor" content="#1f5077"><script type="module" src="/assets/js/vendor-5cdf60a8.js"></script><script type="module" src="/assets/js/main-5d19a6d9.js"></script></head><body class="font-sans text-fg">  <div class="grid-body"> <div class="after:bg-transparent header-container sticky top-0 z-[9999]"> <div class="absolute h-full header-background-stuck left-0 top-0 w-full"></div> <div class="absolute h-full header-background-initial left-0 top-0 w-full"></div> <header id="header" class="flex h-header items-center relative select-none text-fx-lg wrapper"> <div class="flex flex-none h-full items-center relative"> <a href="/"><span class="sr-only">Home</span> <svg class="fill-[--logo-wordmark] i-fm-wordmark-logo w-[120px]" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewbox="0 0 952.5 203.6"> <path d="M21.4 101.8a80.4 80.4 0 0 1 147.3-44.6l15.8 3.1 2-15A101.83 101.83 0 0 0 101.8 0C45.6 0 0 45.6 0 101.8c0 20.9 6.3 40.3 17.1 56.5l15.3 2 2.5-13.9a80.31 80.31 0 0 1-13.5-44.6z" fill="#0067b9"></path> <path d="M186.7 45.7c-.1-.1-.2-.2-.3-.4l-17.8 11.9c.1.1.2.2.3.4a79.89 79.89 0 0 1 13.3 44.2c0 44.4-36 80.4-80.4 80.4-27.7 0-52.2-14-66.6-35.4-.1-.1-.2-.3-.2-.4l-17.8 11.9c.1.1.2.3.2.4a101.7 101.7 0 0 0 84.4 44.9c56.2 0 101.8-45.6 101.8-101.8 0-20.7-6.2-40-16.9-56.1z" fill="#69b3e7"></path> <path d="M101.8 101.8 53.4 69.5V134c.5-.3.9-.6 0 0l30.4-9.4 18-22.8z" fill="#ffc107"></path> <path class="fill-inherit" d="M53.4 134h93.4c1.9 0 3.4-1.5 3.4-3.4V69.5L53.4 134zm292.5-99.1V54h-62.2v40h54.8v19.1h-54.8v55.5h-22.1V34.9h84.3zm89.8 132.6v1.1h-19.3c-.9-1.9-1.7-3.7-2.2-5.6-8.4 4.3-20.2 7.4-30.1 7.4-22.5 0-35.8-11.1-35.8-30.4 0-18.9 16.5-31.4 42-31.4 8.4 0 14.5.7 20.2 1.7v-2.8c0-13.9-8.4-20.8-23.4-20.8-9.1 0-18.9 1.5-28.8 4.8l-5.4-15.4c12.6-4.6 24.3-7.1 36.4-7.1 16.2 0 25.6 4.1 32.1 10.4 6.7 6.7 9.7 16.3 9.7 28V138c-.1 9.8 1.2 20.6 4.6 29.5zm-48.3-13.6c7.4 0 16.2-1.9 23-5.4V125c-5.9-1.1-10.6-1.7-18.8-1.7-15.2 0-23 5.9-23 15.8 0 10 6.7 14.8 18.8 14.8zm136-79.1-5.2 15.6c-9.8-3-19.7-4.5-29.5-4.5-11.9 0-17.5 4.5-17.5 10.6 0 6.3 4.3 10 19.9 13.9 27.7 6.9 37.9 15.4 37.9 30.1 0 19.9-14.9 29.9-42 29.9-13.2 0-26.7-2.2-39.4-6.5l5.4-15.6c11 3.3 23.6 5.4 34 5.4 14.9 0 21.4-3.9 21.4-11.1 0-5.9-4.5-9.8-23.2-14.3-25.4-6.1-34.2-15-34.2-30.6 0-16.5 13.4-28.6 37.7-28.6 12.2 0 23.7 2 34.7 5.7zm78.2 91.6c-6.3 2.6-14.9 4.1-22.1 4.1-8.5 0-16.3-2.2-21.2-7.1-5-5-7.2-11.5-7.2-22.5V88.6h-15.8V70.9h15.8V47.4h21.2V71H597v17.6h-24.7v49.6c0 10 4.5 14.5 13 14.5 4.5 0 9.3-.9 13.2-2l3.1 15.7zm160.7-62v64.2H741v-61.1c0-12.8-7.8-20.2-20.2-20.2-7.6 0-15.8 1.9-21.7 5.2v76.1h-21.2v-61.8c0-13.7-6.9-19.5-18.8-19.5-6.9 0-15.6 2.2-23 6.3v75h-21.4V70.9h20.1v6.7c8.7-5.2 20.6-8.5 31.9-8.5 9.8 0 19.1 3.5 25.8 9.7 9.8-5.9 22.8-9.7 35.5-9.7 10.8 0 19.9 3.5 25.4 9.3 6.3 6.3 8.9 14.3 8.9 26zm104.1 63.1v1.1h-19.3c-.9-1.9-1.7-3.7-2.2-5.6-8.4 4.3-20.2 7.4-30.1 7.4-22.5 0-35.8-11.1-35.8-30.4 0-18.9 16.5-31.4 42-31.4 8.4 0 14.5.7 20.2 1.7v-2.8c0-13.9-8.4-20.8-23.4-20.8-9.1 0-18.9 1.5-28.8 4.8l-5.4-15.4c12.6-4.6 24.3-7.1 36.4-7.1 16.2 0 25.6 4.1 32.1 10.4 6.7 6.7 9.7 16.3 9.7 28V138c-.1 9.8 1.2 20.6 4.6 29.5zm-48.3-13.6c7.4 0 16.2-1.9 23-5.4V125c-5.9-1.1-10.6-1.7-18.8-1.7-15.2 0-23 5.9-23 15.8.1 10 6.7 14.8 18.8 14.8zm88.7-120.1v18.4h-21.4V33.8h21.4zm0 37.1v97.7h-21.4V70.9h21.4zm45.7-39.7v137.4h-21.3V31.2h21.3z" fill="currentColor"></path> </svg> </a> </div> <div class="navigation-wrapper z-0"> <input id="menu-toggle" type="checkbox" role="button" aria-controls="primary-navigation" aria-expanded="false" aria-haspopup="true"> <label for="menu-toggle"> <span class="collasped-text sr-only">Open menu</span> <span class="expanded-text sr-only">Hide menu</span> <svg class="i-hamburger size-icon-lg stroke-[2.25]" stroke="currentColor" stroke-width="1.25" stroke-linecap="round" stroke-linejoin="round" fill="none" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewbox="0 0 32 32"> <path d="M5 9H27"></path> <path d="M5 16H27"></path> <path d="M5 23H27"></path> </svg> </label> <div id="side-nav-overlay" class="lg:hidden"></div> <ul id="primary-navigation"> <li class="bg-white left-0 lg:hidden sticky top-0 w-full z-10"></li> <li class="top-level-wrapper"> <a href="/features/" class="block top-level-nav-item"> <div class="label-wrapper"> <p class="text-fx-lg trim">Product tour</p> </div> </a> </li> <li class="top-level-wrapper"> <a href="/business/" class="block top-level-nav-item"> <div class="label-wrapper"> <p class="text-fx-lg trim">For business</p> </div> </a> </li> <li class="top-level-wrapper"> <details name="top-level" class="group/details"> <summary class="expandable top-level-nav-item"> <div class="label-wrapper"> <p class="text-fx-lg trim">Support & Resources</p> </div> <svg xmlns="http://www.w3.org/2000/svg" class="fill-none group-open/details:rotate-180 size-icon-sm" stroke="currentColor" stroke-width="1.25" stroke-linecap="round" stroke-linejoin="round" fill="none" aria-hidden="true"> <use class="i-chevron" href="#i-chevron"></use> </svg> </summary> <ul class="second-level-wrapper"> <li> <p class="font-semibold lg:text-fx-lg text-fx-lg trim">Support</p> <ul class="third-level-wrapper"> <li> <a href="https://fastmail.help/" class="group"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> Fastmail help center</span> </p> </a> </li> <li> <a href="/support/" class="group"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> Contact Fastmail support</span> </p> </a> </li> <li> <a href="https://fastmailstatus.com/" class="group"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> System status</span> </p> </a> </li> <li> <a href="/bug-bounty/" class="group"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> Report a security issue</span> </p> </a> </li> </ul> </li> <li> <p class="font-semibold lg:text-fx-lg text-fx-lg trim">How to</p> <ul class="third-level-wrapper"> <li> <a href="/how-to/move-from-gmail/" class="group"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> Move from Gmail</span> </p> </a> </li> <li> <a href="/how-to/move-from-outlook/" class="group"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> Move from Outlook</span> </p> </a> </li> <li> <a href="/how-to/move-from-yahoo/" class="group"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> Move from Yahoo</span> </p> </a> </li> <li> <a href="/how-to/move-from-proton/" class="group"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> Move from Proton</span> </p> </a> </li> <li> <a href="/how-to/move-from-hey/" class="group"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> Move from HEY</span> </p> </a> </li> <li> <a href="/how-to/email-for-your-domain/" class="group"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> Get email for your domain</span> </p> </a> </li> <li> <a href="/how-to/stop-spam/" class="group"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> Stop spam</span> </p> </a> </li> <li> <a href="/how-to/inbox-zero/" class="group"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> Achieve inbox zero</span> </p> </a> </li> </ul> </li> <li> <p class="font-semibold lg:text-fx-lg text-fx-lg trim">Resources</p> <ul class="third-level-wrapper"> <li> <a href="/blog/" class="group"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> Blog</span> </p> </a> </li> <li> <a href="/digitalcitizen/" class="group"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> Podcast</span> </p> </a> </li> <li> <a href="/company/about/" class="group"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> About us</span> </p> </a> </li> <li> <a href="/company/values/" class="group"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> Our values</span> </p> </a> </li> <li> <a href="/dev/" class="group"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="current-page lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link relative whitespace-normal"> API Documentation</span> </p> </a> </li> </ul> </li> <li> <p class="font-semibold lg:text-fx-lg text-fx-lg trim">Download the app</p> <ul class="third-level-wrapper"> <li> <a href="https://apps.apple.com/us/app/fastmail-email-calendar/id931370077" class="group" target="_blank"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> App Store</span> <svg xmlns="http://www.w3.org/2000/svg" class="align-text-bottom inline size-icon" stroke="currentColor" stroke-width="1.25" stroke-linecap="round" stroke-linejoin="round" fill="none" aria-labelledby="external-link-title-a49889" role="graphics-symbol"> <title id="external-link-title-a49889">Download Fastmail on the App Store</title> <use class="i-external-link" href="#i-external-link"></use> </svg> </p> </a> </li> <li> <a href="https://play.google.com/store/apps/details?id=com.fastmail.app" class="group" target="_blank"> <p class="lg:max-w-max py-fx-4 text-fx-lg trim whitespace-nowrap"> <span class="lg:[--link-color:--theme-fg] lg:group-hover:link-underline lg:link whitespace-normal"> Google Play</span> <svg xmlns="http://www.w3.org/2000/svg" class="align-text-bottom inline size-icon" stroke="currentColor" stroke-width="1.25" stroke-linecap="round" stroke-linejoin="round" fill="none" aria-labelledby="external-link-title-7c7214" role="graphics-symbol"> <title id="external-link-title-7c7214">Download Fastmail on Google Play</title> <use class="i-external-link" href="#i-external-link"></use> </svg> </p> </a> </li> </ul> </li> </ul> </details> </li> <li class="top-level-wrapper"> <a href="/pricing/" class="block top-level-nav-item"> <div class="label-wrapper"> <p class="text-fx-lg trim">Pricing</p> </div> </a> </li> <span class="flex-grow ge-[64rem]:hidden"></span> <li class="bg-white bottom-0 flex flex-col gap-fx-2 left-0 lg:hidden pb-fx-6 pt-fx-2 px-fx-4 right-0 sticky text-center"> <a href="https://app.fastmail.com/"> <p class="active:bg-grey-100/20 bg-grey-100/10 hover:bg-grey-100/15 py-fx-4 rounded-md text-blue-120 text-fx-lg trim w-full">Log in</p> </a> <a href="https://app.fastmail.com/signup/"> <p class="active:bg-blue-120 bg-blue-100 font-semibold hover:bg-blue-110 py-fx-4 rounded-md text-fx-lg text-white trim w-full">Try for free</p> </a> </li> </ul> </div> <ul class="flex flex-1 flex-row-reverse flex-wrap gap-x-fx-2 gap-y-fx-10 overflow-hidden self-stretch"> <li class="flex items-center lt-[22.5rem]:hidden min-h-header product-nav-wrapper"> <a href="https://app.fastmail.com/signup/"> <div class="active:bg-[--header-signup-bg-active] bg-[--header-signup-bg] border border-[--header-signup-border] flex hover:bg-[--header-signup-bg-hover] items-center px-fx-5 py-[10.5px] rounded-md text-nowrap"> <p class="font-semibold text-[--header-signup-fg] text-fx-lg trim">Try for free</p> </div> </a> </li> <li class="flex items-center lt-[22.5rem]:hidden overflow-hidden product-nav-wrapper whitespace-nowrap"> <a href="https://app.fastmail.com/" class="py-fx-3 top-level-nav-item"> <div class="label-wrapper mx-fx-5"> <p class="text-fx-lg trim">Log in</p> </div> </a> </li> </ul> </header> </div> <main> <header class="[background-image:--hero-gradient] hero-generic overflow-hidden relative supports-[overflow:clip]:overflow-clip"> <div class="absolute bg-[--hero-gradient] grid grid-cols-[1fr_minmax(0,var(--grid-max-width))_1fr] grid-rows-[100%] inset-0"> <div class="aspect-square bg-blue-100 col-[2/-1] ml-[--outer-margin-left] opacity-30 relative rounded-full row-[1] top-[--outer-margin-top] w-[150%]"></div> <div class="col-[3] place-self-end row-[1]"> <div class="bg-lightblue-100 h-[--circle-height] opacity-30 rounded-t-full w-[--circle-width]"></div> </div> </div> <div class="-mt-header pb-8xl pt-[calc(var(--fluid-space-7xl)+var(--header-height))] relative space-y-2xl text-center text-pretty text-white wrapper"> <h1 class="font-normal font-serif text-9 trim">API Documentation</h1> <p class="max-w-prose mx-auto text-1 trim"></p> </div> </header> <article class="pb-7xl prose prose-grid pt-xl"> <h2 id="welcome-developers" tabindex="-1">Welcome, developers!</h2> <p><strong>Looking to integrate with Fastmail? You’ve come to the right place.</strong></p> <p>Fastmail supports open standards. We provide full support for access to the data in your Fastmail account over the following open protocols:</p> <ul> <li>Mail — you can access mail via <a href="https://www.rfc-editor.org/rfc/rfc8621.html" target="_blank" rel="noopener">JMAP</a>, <a href="https://www.ietf.org/rfc/rfc9051.html" target="_blank" rel="noopener">IMAP</a>, or <a href="https://www.rfc-editor.org/rfc/rfc1939" target="_blank" rel="noopener">POP</a> and send via <a href="https://www.rfc-editor.org/rfc/rfc8621.html" target="_blank" rel="noopener">JMAP</a> or <a href="https://www.rfc-editor.org/rfc/rfc5321.html" target="_blank" rel="noopener">SMTP</a>.</li> <li>Contacts — you can access via <a href="https://www.rfc-editor.org/rfc/rfc6352" target="_blank" rel="noopener">CardDAV</a>. We will be opening up JMAP access as well, as soon as the specification is finalized.</li> <li>Calendars — you can access via <a href="https://www.rfc-editor.org/rfc/rfc4791" target="_blank" rel="noopener">CalDAV</a>. We will be opening up JMAP access as well, as soon as the specification is finalized.</li> <li>Files — you can access via <a href="https://www.rfc-editor.org/rfc/rfc4918" target="_blank" rel="noopener">WebDAV</a>.</li> </ul> <p>The full API specification documents are linked above, and there are many libraries, tutorials, and other resources on the internet for building with these open protocols, so we won’t repeat it all here.</p> <p>The most important thing to note are the authentication requirements. If you are building an app to distribute to others, you should implement OAuth to allow users to easily and securely authenticate. You can use OAuth with all of our supported protocols; please see our guide below for more information on integrating OAuth with Fastmail.</p> <p>For testing purposes, or building an app for just yourself, you can generate an API token (for JMAP access), or an app password (for everything else) in <a href="https://app.fastmail.com/settings/security/integrations" target="_blank" rel="noopener">Settings → Privacy & Security → Integrations</a>.</p> <h2 id="getting-started-with-jmap" tabindex="-1">Getting started with JMAP</h2> <p>JMAP is a modern protocol that provides standard methods for efficiently synchronising data with a server. It lets us provide a consistent interface to all the different data types in a Fastmail account, such as emails, calendar events, or contacts.</p> <p>Like most modern APIs, JMAP uses HTTP and JSON so it’s easy to implement in just about any language. We’ve written a short <a href="https://jmap.io/crash-course.html" target="_blank" rel="noopener">JMAP crash course</a>, and published open source <a href="https://github.com/fastmail/JMAP-Samples" target="_blank" rel="noopener">sample code</a> to our GitHub account to help you get started.</p> <p>To start using a JMAP API you need two things: the URL of the JMAP Session resource and authentication credentials. The JMAP session resource can be found at <code>https://api.fastmail.com/jmap/session</code>. To authenticate, you’ll need an API token, as discussed above.</p> <p>To use an API token, add an <code>Authorization</code> header set to <code>Bearer {value}</code>, where <code>{value}</code> is the value of the token to your API request. Our JMAP APIs are CORS enabled so you can create integrations directly from a web app, as well as from a server or native code.</p> <h2 id="masked-email-api" tabindex="-1">Masked Email API</h2> <p>We support a JMAP extension to allow apps to manage a user’s Masked Email addresses. The <code>https://www.fastmail.com/dev/maskedemail</code> capability is advertised to represent support for the MaskedEmail data type and associated methods.</p> <p>Each MaskedEmail object contains a number of metadata fields: <code>createdBy</code>, <code>forDomain</code>, <code>url</code> and <code>description</code>. Make sure you set these correctly so the Fastmail app and other products all interoperate.</p> <p>The <code>createdBy</code> 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 <strong>not</strong> try to set this.</p> <p><em>If</em> your product is a password manager, the <code>forDomain</code> property should be the protocol and domain (i.e. origin) of the site the user is using the masked email for. It should <strong>not</strong> include any path or other components. Example: <code>https://www.example.com</code></p> <p><em>If</em> your product supports deep links, the <code>url</code> 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 <code>null</code>. Do <strong>not</strong> set this to the domain of the site the user is using the masked email for, see above and use <code>forDomain</code> for this.</p> <p>The <code>description</code> 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 <strong>not</strong> set this to the name of your product, see <code>createdBy</code> above which is used for this. Do <strong>not</strong> set this to the domain of the site the user is using the masked email for, see above and use <code>forDomain</code> for this.</p> <h3 id="the-masked-email-data-type" tabindex="-1">The MaskedEmail data type</h3> <p>This capability adds support for a new MaskedEmail data type, with the following properties:</p> <ul> <li><strong>id</strong>: <code>String</code> (immutable; server-set)<br> The id of the masked email address.</li> <li><strong>email</strong>: <code>String</code> (immutable; server-set)<br> The email address.</li> <li><strong>state</strong>: <code>String</code> (default: pending)<br> This MUST be one of: - <code>pending</code>: 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. - <code>enabled</code>: the address is active and receiving mail normally. - <code>disabled</code>: the address is active, but mail is sent straight to trash. - <code>deleted</code>: the address is inactive; any mail sent to the address is bounced.</li> <li><strong>forDomain</strong>: <code>String</code><br> 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.</li> <li><strong>description</strong>: <code>String</code><br> 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.</li> <li><strong>lastMessageAt</strong>: <code>UTCDate|null</code> (server-set)<br> The date-time the most recent message was received at this email address, if any.</li> <li><strong>createdAt</strong>: <code>UTCDate</code> (immutable; server-set)<br> The date-time the email address was created.</li> <li><strong>createdBy</strong>: <code>String</code> (immutable; server-set)<br> 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”.</li> <li><strong>url</strong>: <code>String|null</code><br> 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.</li> <li><strong>emailPrefix</strong>: <code>String</code> (create-only)<br> 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).</li> </ul> <p>There are two methods added by the capability</p> <h3 id="masked-email-get" tabindex="-1">MaskedEmail/get</h3> <p>This is a standard “/get” method as described in <a href="https://www.rfc-editor.org/rfc/rfc8620.html#section-5.1" target="_blank" rel="noopener">RFC8620, Section 5.1</a>. The “ids” argument may be <code>null</code> to fetch all at once.</p> <h3 id="masked-email-set" tabindex="-1">MaskedEmail/set</h3> <p>This is a standard “/set” method as described in <a href="https://www.rfc-editor.org/rfc/rfc8620.html#section-5.3" target="_blank" rel="noopener">RFC8620, Section 5.3</a>.</p> <p>The email address will be generated by the server as follows:</p> <ol> <li>The domain will be set as per the Masked Email domain setting for the customer to which the user belongs.</li> <li>The mailbox will start with the given “emailPrefix” if provided, otherwise, the server will generate a random one from a predefined corpus.</li> </ol> <p>To prevent abuse, there are rate limits in place. A standard JMAP <code>rateLimit</code> SetError will be returned on create if these are exceeded.</p> <h2 id="o-auth-at-fastmail" tabindex="-1">OAuth at Fastmail</h2> <p>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 <a href="https://www.rfc-editor.org/rfc/rfc6749.html" target="_blank" rel="noopener">RFC 6749</a>.</p> <h3 id="scopes" tabindex="-1">Scopes</h3> <p>The following scopes are currently supported:</p> <dl> <dt><strong>urn:ietf:params:jmap:core</strong></dt> <dd>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.</dd> <dt><strong>urn:ietf:params:jmap:mail</strong></dt> <dd>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 <a href="https://www.rfc-editor.org/rfc/rfc8621.html#section-1.3.1" target="_blank" rel="noopener">RFC8621</a>.</dd> <dt><strong>urn:ietf:params:jmap:submission</strong></dt> <dd>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 <a href="https://www.rfc-editor.org/rfc/rfc8621.html#section-1.3.1" target="_blank" rel="noopener">RFC8621</a>.</dd> <dt><strong>urn:ietf:params:jmap:vacationresponse</strong></dt> <dd>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.</dd> <dt><strong>https://www.fastmail.com/dev/maskedemail</strong></dt> <dd>This grants the ability to read and write the MaskedEmail data type, as documented above.</dd> </dl> <h2 id="registration" tabindex="-1">Registration</h2> <p>Clients are currently registered manually by contact with Fastmail developers. Want to connect your app with OAuth? <a href="/company/partners/">Check out our partnerships page and get in touch!</a></p> <p>We’ll need the following information to register your client, but we can update this later, so don’t worry if you’re starting something new and don’t have everything to hand yet — we’d still love to hear from you.</p> <ul> <li><strong>clientName</strong>: The name of your app, to be shown to the user during authorization.</li> <li><strong>logoUrl</strong>: The URL for a logo to display for your app. This will be rendered in a square shape.</li> <li><strong>clientUrl</strong>: The URL of a web page providing information about your app (e.g. the page on the App store, your website, or a GitHub link).</li> <li><strong>tosUrl</strong>: The URL for your terms of service.</li> <li><strong>policyUrl</strong>: The URL for your privacy policy.</li> <li><strong>supportUrl</strong>: The URL of a web page that tells users how to contact you for support with your app.</li> <li><strong>scopes:</strong> The list of scopes your app may request access for. This should be the minimal set of scopes needed for your app to function. For example, if you are building a password manager that just manages the user’s Masked Email addresses, you should not request the <code>urn:ietf:params:jmap:mail</code> scope, which would give access to the messages the user receives, as the app has no need for this.</li> <li><strong>redirectUris</strong>: A list of redirect URIs the client may use in the OAuth flow. You can register as many as you like. Each redirect URI: <ul> <li>MUST be a full URI including path if desired.</li> <li>MAY include query parameters.</li> <li>MUST NOT include a fragment part (<code>#</code>).</li> <li>MUST NOT include path traversal (<code>[\/]..</code>).</li> <li>MUST start with one of: <ul> <li>An https domain you own, e.g. <code>https://example.com/</code> (This is referred to as a “claimed https URI” in OAuth docs.)</li> <li>A private-use URI scheme in reverse domain notation, e.g. <code>com.example:/</code>. Such a scheme MUST have at least one dot in it. It SHOULD be formed from a domain you own.</li> <li><code>http://localhost/</code> – the loopback URL. During authorization, an arbitrary port may be given by the client, and <code>localhost</code> may be replaced by either <code>127.0.0.1</code> or <code>::1</code>.</li> </ul> </li> </ul> </li> <li><strong>clientOrigins</strong>: A list of origins the client may use to make <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS" target="_blank" rel="noopener">CORS</a> requests to the token endpoint and JMAP API. If your app is a web app and connecting directly to our API (rather than via your servers), you’ll need to ensure you register the origins you will be using for it to work. If you are not building a web-based app, you don’t need this.</li> </ul> <p>We will assign a client id for the registration and send it back to you.</p> <p>If the client supports OAuth with multiple authorization servers (e.g. it adds support for another email service) it MUST NOT reuse the same redirect URI with different registrations. (For example, it should add a per-service path component.) This allows it to detect and prevent server mix-up attacks (see the state parameter below).</p> <h2 id="authorization" tabindex="-1">Authorization</h2> <p>Clients initiate authorization by opening the user’s web browser at the Fastmail OAuth Authorization URL:</p> <p><code>https://api.fastmail.com/oauth/authorize</code></p> <p>The following URL parameters MUST be present:</p> <ul> <li><strong>client_id</strong>: The client id for the application, given to the developer when your application is registered.</li> <li><strong>redirect_uri</strong>: One of the redirect URIs previously registered with Fastmail. This MUST be identical to the registered URI. The one exception to this is if a URI with the prefix <code>http://localhost/</code> was registered, in which case the matching URI MUST also include an arbitrary port and MAY use 127.0.0.1 or ::1 instead of <code>localhost</code>.</li> </ul> <p>For example, if <code>http://localhost/redirect</code> was registered, then the client could send <code>http://127.0.0.1:49152/redirect</code> as the redirect_uri for authorization.</p> <ul> <li><strong>response_type</strong>: This MUST be “code”. No other value is accepted at this time.</li> <li><strong>scope</strong>: A space delimited set of scopes the client would like access to. This MUST be a subset of the scopes registered for the client.</li> <li><strong>code_challenge</strong>: A PKCE code challenge as per <a href="https://www.rfc-editor.org/rfc/rfc7636.html" target="_blank" rel="noopener">RFC 7636</a>, using SHA-256. To generate a challenge, first generate a “code_verifier”: a high-entropy cryptographic random string using the characters <code>[A-Z] / [a-z] / [0-9] / "-" / "." / "*" / "~"</code> (the unreserved characters from Section 2.3 of <a href="https://www.rfc-editor.org/rfc/rfc3986.html" target="_blank" rel="noopener">RFC 3986</a>), with a minimum length of 43 characters and a maximum length of 128 characters. The code_challenge is then <code>BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))</code>.</li> <li><strong>code_challenge_method</strong>: The only accepted value at this time is “S256”.</li> <li><strong>state</strong>: An opaque value used by the client to verify that an authorization response is due to a request that the client initiated. The Fastmail server will include this value when redirecting the user-agent back to the client. Clients MUST generate a state with a unique, unguessable random string when initiating an authorization request. When a response is received, the client MUST: - Verify that the state returned matches exactly the state it sent, to verify that this request was indeed initiated by the client and not an attacker. - Verify that the redirect URI the authorization response came in on was the one they used when generating the request. This prevents Mix-Up Attacks when the client supports more than one authorization server.</li> </ul> <p>Other URL parameters MAY be supplied but will be ignored.</p> <p>Fastmail will authenticate the user and ask them if they wish to grant authorization to the client. If successful, the client will receive a response via the redirect_uri, which will include the following query parameters:</p> <ul> <li><strong>code</strong>: The authorization code. This may be exchanged for the refresh token. It expires 10 minutes after authorization. It MUST NOT be used again once the client has successfully exchanged it for a refresh token. This will result in all authentication tokens associated with it being immediately revoked.</li> <li><strong>state</strong>: The value of the state parameter that was passed in with the initial request.</li> </ul> <p>If the authorization fails due to a missing or invalid client_id or redirect_uri parameter, the user agent will not redirect back to the client. Otherwise, the client will receive a response via the redirect_uri, which will include the following query parameters:</p> <ul> <li><strong>error</strong>: An error type, as per <a href="https://www.rfc-editor.org/rfc/rfc6749.html#section-4.1.2.1" target="_blank" rel="noopener">RFC 6749, section 4.1.2.1</a>.</li> <li><strong>state</strong>: The value of the state parameter that was passed in with the initial request.</li> </ul> <h3 id="obtaining-a-refresh-token" tabindex="-1">Obtaining a refresh token</h3> <p>Following authorization, the client will obtain initial refresh tokens and access tokens by making a POST request to the Fastmail token endpoint:</p> <p><code>https://api.fastmail.com/oauth/refresh</code></p> <p>The following parameters MUST be present, using the “application/x-www-form-urlencoded” format with a character encoding of UTF-8 in the HTTP request entity-body:</p> <ul> <li><strong>client_id</strong>: The client id for the application, given to the developer when your application is registered.</li> <li><strong>redirect_uri</strong>: The redirect_uri parameter sent with the authorization request from which the code was obtained.</li> <li><strong>grant_type</strong>: This MUST be “authorization_code”.</li> <li><strong>code</strong>: The code returned via the redirect back from authorization.</li> <li><strong>code_verifier</strong>: The code_verifier generated for the authorization, as per <a href="https://www.rfc-editor.org/rfc/rfc7636.html" target="_blank" rel="noopener">RFC 7636</a>.</li> </ul> <p>Other parameters MAY be supplied but will be ignored.</p> <p>The server will verify the parameters and if successful, return a <code>200 OK</code> response with a content type of <code>application/json</code>. The body will be a JSON object with the following properties:</p> <ul> <li><strong>access_token</strong>: <code>String</code> A bearer token used to authenticate API requests. This will be valid for a fixed, limited time.</li> <li><strong>token_type</strong>: <code>String</code> The type of the access token. For now, this will always be “bearer”.</li> <li><strong>expires_in</strong>: <code>Number</code> The lifetime in seconds of the access token. For example, the value <code>3600</code> denotes that the access token will expire in one hour from the time the response was generated.</li> <li><strong>scope</strong>: <code>String</code> The space delimited set of scopes that this access token may use.</li> <li><strong>refresh_token</strong>: <code>String</code> The refresh token to use next time the client needs to get a new access token.</li> </ul> <p>If the request fails, the server will return an appropriate HTTP error response, probably <code>400 Bad Request</code>, with a content type of <code>application/json</code>. The body will be a JSON object with the following property:</p> <ul> <li><strong>error</strong>: <code>String</code> A single ASCII error code indicating why the request failed, with a value as per <a href="https://www.rfc-editor.org/rfc/rfc6749.html#section-5.2" target="_blank" rel="noopener">RFC 6749, Section 5.2</a>.</li> </ul> <h3 id="getting-a-new-access-token" tabindex="-1">Getting a new access token</h3> <p>Your client should keep using the access token it has been issued until the token expires, which will result in getting a <code>401</code> HTTP response back.</p> <p>When the access token expires, the client must get a new one by making a POST request to the Fastmail token endpoint again. The following parameters MUST be present, using the “application/x-www-form-urlencoded” format with a character encoding of UTF-8 in the HTTP request entity-body:</p> <ul> <li><strong>client_id</strong>: The client id for the application, given to the developer when your application is registered.</li> <li><strong>grant_type</strong>: This MUST be “refresh_token”.</li> <li><strong>refresh_token</strong>: The refresh token returned last time the client obtained a new access token.</li> </ul> <p>The success and failures responses are identical to those documented in the “obtaining a refresh token” section above.</p> <p>In the case of an “invalid_grant” error, there MAY be an additional property called “temporary”. If this is present and the value is true, the refresh token MAY become valid again at some point in the future. (This can happen if a user is locked by their admin, but then unlocked again at a later point.) The “error_description” property of the error object SHOULD be present with a user-readable explanation that the client may like to show. If the “temporary” property is not present, an invalid_grant error is permanent and the user will need to go through the OAuth flow again to get a new refresh token if they wish to reconnect to their Fastmail account.</p> <p><strong>Please note</strong>, a new refresh token will be returned in the response and the client MUST replace their previous refresh token with this. The client MUST NOT try to use an old refresh token again; this will result in the authorization being revoked as a protection against leaked refresh tokens. If the user has multiple devices, each client MUST obtain separate authorization. You cannot share a refresh token between devices.</p> <h3 id="revoking-a-token" tabindex="-1">Revoking a token</h3> <p>If a client no longer needs the access it has been granted to an account, it can make an authenticated POST request to the following URL to immediately revoke all associated access tokens and refresh tokens:</p> <p><code>https://api.fastmail.com/oauth/revoke</code></p> </article> </main> <footer class="[--link-color:--brand-color-deepblue-5] [--link-hover:--brand-color-deepblue-5] bg-footer-bg text-fg-footer"> <div class="[background-image:--footer-sep-gradient] h-[4px] w-full"></div> <nav aria-labelledby="footer-navigation" class="flex flex-col gap-y-fx-14 py-fx-14 wrapper"> <h2 id="footer-navigation" class="sr-only">Footer navigation</h2> <div class="flex flex-wrap gap-y-fx-10"> <div class="basis-2/6 flex-grow min-w-[min(18rem,100%)] space-y-fx-4"> <div class="-mt-fx-2"> <svg xmlns="http://www.w3.org/2000/svg" class="size-[40px]" aria-hidden="true"> <use class="i-fm-icon-logo" href="#i-fm-icon-logo"></use> </svg> </div> <p class="font-semibold text-fx-lg trim">Email and calendar made better</p> </div> <div class="basis-4/6 flex flex-grow flex-wrap gap-fx-9"> <div class="basis-[11.25rem] flex-1 space-y-fx-4 text-fx-base"> <h3 class="font-semibold text-fx-lg trim">Product</h3> <ul> <li> <a href="/features/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Product tour</p> </a> </li> <li> <a href="/business/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">For business</p> </a> </li> <li> <a href="/pricing/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Pricing</p> </a> </li> <li> <a href="/features/security/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Security</p> </a> </li> <li> <a href="/features/privacy/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Privacy</p> </a> </li> </ul> </div> <div class="basis-[11.25rem] flex-1 space-y-fx-4 text-fx-base"> <h3 class="font-semibold text-fx-lg trim">How to</h3> <ul> <li> <a href="/how-to/move-from-gmail/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Move from Gmail</p> </a> </li> <li> <a href="/how-to/move-from-outlook/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Move from Outlook</p> </a> </li> <li> <a href="/how-to/move-from-yahoo/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Move from Yahoo</p> </a> </li> <li> <a href="/how-to/move-from-proton/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Move from Proton</p> </a> </li> <li> <a href="/how-to/move-from-hey/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Move from HEY</p> </a> </li> <li> <a href="/how-to/email-for-your-domain/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Get email for your domain</p> </a> </li> <li> <a href="/how-to/stop-spam/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Stop spam</p> </a> </li> <li> <a href="/how-to/inbox-zero/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Achieve inbox zero</p> </a> </li> </ul> </div> <div class="basis-[11.25rem] flex-1 space-y-fx-4 text-fx-base"> <h3 class="font-semibold text-fx-lg trim">Support & Resources</h3> <ul> <li> <a href="/blog/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Blog</p> </a> </li> <li> <a href="/digitalcitizen/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Podcast</p> </a> </li> <li> <a href="https://fastmail.help/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Fastmail help center</p> </a> </li> <li> <a href="/support/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Contact Fastmail support</p> </a> </li> <li> <a href="/dev/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">API Documentation</p> </a> </li> <li> <a href="/bug-bounty/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Report a security issue</p> </a> </li> </ul> </div> <div class="basis-[11.25rem] flex-1 space-y-fx-4 text-fx-base"> <h3 class="font-semibold text-fx-lg trim">Company</h3> <ul> <li> <a href="/company/about/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">About us</p> </a> </li> <li> <a href="/company/values/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Our values</p> </a> </li> <li> <a href="https://apply.workable.com/fastmail-1/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Careers</p> </a> </li> <li> <a href="/company/open-source/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Open source and standards</p> </a> </li> <li> <a href="/company/partners/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Partner with us</p> </a> </li> <li> <a href="/policies/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Policies</p> </a> </li> <li> <a href="/media-kit/" class="inline-block link"> <p class="py-fx-4 text-fx-base trim">Media kit</p> </a> </li> </ul> </div> </div> </div> <div class="border-footer-border border-t flex gap-fx-8 items-center justify-center le-[66rem]:flex-col pt-fx-8 text-fx-base"> <ul class="flex flex-grow flex-wrap gap-fx-4 le-[66rem]:justify-center"> <li>© 2025 Fastmail Pty Ltd. All rights reserved.</li> <li> <a href="https://fastmailstatus.com/" class="link">System status</a> </li> <li> <a href="/policies/terms-of-service/" class="link">Terms of service</a> </li> <li> <a href="/policies/privacy/" class="link">Privacy policy</a> </li> </ul> <div class="flex flex-wrap gap-fx-8 items-center justify-center"> <ul class="flex flex-grow flex-wrap gap-fx-6 items-center le-[66rem]:justify-center"> <li> <a href="https://mastodon.social/@fastmail"><span class="sr-only">Mastodon</span> <svg xmlns="http://www.w3.org/2000/svg" class="size-icon" fill="none" aria-hidden="true"> <use class="i-mastodon" href="#i-mastodon"></use> </svg> </a> </li> <li> <a href="https://twitter.com/Fastmail"><span class="sr-only">X</span> <svg xmlns="http://www.w3.org/2000/svg" class="size-icon" fill="none" aria-hidden="true"> <use class="i-x" href="#i-x"></use> </svg> </a> </li> <li> <a href="https://www.linkedin.com/company/fastmail"><span class="sr-only">LinkedIn</span> <svg xmlns="http://www.w3.org/2000/svg" class="size-icon" fill="none" aria-hidden="true"> <use class="i-linkedin" href="#i-linkedin"></use> </svg> </a> </li> <li> <a href="https://www.facebook.com/Fastmail/"><span class="sr-only">Facebook</span> <svg xmlns="http://www.w3.org/2000/svg" class="size-icon" fill="none" aria-hidden="true"> <use class="i-facebook" href="#i-facebook"></use> </svg> </a> </li> </ul> <ul class="flex flex-grow flex-wrap gap-fx-8 items-center le-[66rem]:justify-center"> <li> <a href="https://play.google.com/store/apps/details?id=com.fastmail.app"> <img src="/assets/images/play-store-_nKvx1K1d--135.svg" alt="Google Play" loading="lazy" decoding="async" width="135" height="40"> </a> </li> <li> <a href="https://apps.apple.com/us/app/fastmail-email-calendar/id931370077"> <img src="/assets/images/app-store-ZOqpK4vo0n-120.svg" alt="App Store" loading="lazy" decoding="async" width="120" height="40"> </a> </li> </ul> </div> </div> </nav> </footer> </div> <svg id="icon-sprite-sheet" class="sr-only"> <defs> <g id="i-chevron"> <svg xmlns="http://www.w3.org/2000/svg" viewbox="0 0 24 24"> <polyline points="17.75 9.13 12 14.88 6.25 9.13"></polyline> </svg> </g> <g id="i-external-link"> <svg viewbox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"> <path d="M16.83 12.81V17.64C16.83 18.067 16.6604 18.4765 16.3584 18.7784C16.0565 19.0804 15.647 19.25 15.22 19.25H6.36C5.933 19.25 5.52349 19.0804 5.22156 18.7784C4.91962 18.4765 4.75 18.067 4.75 17.64V8.77998C4.75 8.35298 4.91962 7.94347 5.22156 7.64154C5.52349 7.33961 5.933 7.16998 6.36 7.16998H11.19"></path> <path d="M14.42 4.75H19.25V9.58"></path> <path d="M10.39 13.61L19.25 4.75"></path> </svg> </g> <g id="i-fm-icon-logo"> <svg viewbox="0 0 40 40" xmlns="http://www.w3.org/2000/svg"> <path d="M19.9998 19.9995L11.6665 14.2695V25.7279L16.8748 24.1645L19.9998 19.9995Z" fill="#FFC107"></path> <path d="M11.6665 25.7298H27.2915C27.8665 25.7298 28.3332 25.2632 28.3332 24.6882V14.2715L11.6665 25.7298Z" fill="#F4F5F7"></path> <path d="M32.8707 11.151C34.6034 13.6674 35.6234 16.7129 35.6234 20.0001C35.6234 28.6292 28.6271 35.6256 19.998 35.6256C14.6562 35.6256 9.94344 32.9401 7.12707 28.8492L4.37435 28.7492L3.52344 31.3274C7.13071 36.5638 13.1616 40.0001 19.9998 40.0001C31.0453 40.0001 39.9998 31.0456 39.9998 20.0001C39.9998 15.7929 38.6943 11.8947 36.4762 8.67285L33.7507 8.74921L32.8707 11.151Z" fill="#69B3E7"></path> <path d="M4.37455 20C4.37455 11.3709 11.3709 4.37455 20 4.37455C25.3418 4.37455 30.0545 7.06 32.8709 11.1509L36.4745 8.67273C32.8691 3.43636 26.8382 0 20 0C8.95455 0 0 8.95455 0 20C0 24.2073 1.30545 28.1055 3.52364 31.3273L7.12727 28.8491C5.39455 26.3327 4.37455 23.2873 4.37455 20Z" fill="#0067B9"></path> </svg> </g> <g id="i-mastodon"> <svg xmlns="http://www.w3.org/2000/svg" viewbox="0 0 20 20"> <mask id="mask0_714_15451" style="mask-type:luminance" maskunits="userSpaceOnUse" x="0" y="0" width="20" height="20"> <path d="M20 0H0V20H20V0Z" fill="white"></path> </mask> <g mask="url(#mask0_714_15451)"> <path fill-rule="evenodd" clip-rule="evenodd" d="M19.625 12C19.375 13.375 17 15 14.25 15.25C12.875 15.375 11.5 15.5 10 15.5C7.625 15.375 5.75 15 5.75 15V15.625C6 17.875 8.125 18 10 18C12 18.125 13.75 17.5 13.75 17.5L13.875 19.125C13.875 19.125 12.5 19.75 10.125 19.875C8.75 20 7.125 19.875 5.125 19.375C0.875 18.375 0.125 14.25 0 10V6.5C0 2.125 3 0.875 3 0.875C4.625 0.25 7.25 0 10 0C12.75 0 15.375 0.25 16.875 1C16.875 1 19.875 2.25 19.875 6.625C20 6.625 20 9.75 19.625 12ZM16.375 6.875V12.125H14.125V7C14.125 5.875 13.625 5.375 12.625 5.375C11.5 5.375 11 6 11 7.25V10H8.875V7.375C8.875 6.125 8.375 5.5 7.25 5.5C6.25 5.375 5.875 6 5.875 7V12.125H3.625V6.875C3.625 5.75 3.875 5 4.5 4.375C5.125 3.75 5.875 3.375 6.875 3.375C8 3.375 8.875 3.75 9.5 4.625L10 5.5L10.5 4.625C11.125 3.75 11.875 3.375 13.125 3.375C14.125 3.375 14.875 3.75 15.5 4.375C16.125 5 16.375 5.875 16.375 6.875Z" fill="#999EA3"></path> </g> </svg> </g> <g id="i-x"> <svg xmlns="http://www.w3.org/2000/svg" viewbox="0 0 24 24"> <path d="M13.676 10.622L20.233 3H18.679L12.986 9.618L8.43897 3H3.19397L10.07 13.007L3.19397 21H4.74797L10.76 14.011L15.562 21H20.807L13.676 10.622ZM11.548 13.096L10.851 12.099L5.30797 4.17H7.69497L12.169 10.569L12.866 11.566L18.681 19.884H16.294L11.548 13.096Z" fill="#999EA3"></path> </svg> </g> <g id="i-linkedin"> <svg xmlns="http://www.w3.org/2000/svg" viewbox="0 0 24 24"> <path fill-rule="evenodd" clip-rule="evenodd" d="M20.551 2H3.508C2.693 2 2 2.645 2 3.439V20.56C2 21.355 2.454 22 3.27 22H20.314C21.13 22 22.001 21.355 22.001 20.56V3.439C22.001 2.645 21.368 2 20.551 2ZM9.619 9.619H12.311V10.991H12.341C12.751 10.251 13.964 9.5 15.463 9.5C18.34 9.5 19.143 11.028 19.143 13.857V19.143H16.286V14.378C16.286 13.111 15.78 12 14.597 12C13.161 12 12.476 12.972 12.476 14.569V19.143H9.619V9.619ZM4.857 19.143H7.714V9.619H4.857V19.143ZM8.071 6.286C8.071 7.273 7.272 8.072 6.285 8.072C5.298 8.072 4.499 7.273 4.499 6.286C4.499 5.299 5.298 4.5 6.285 4.5C7.272 4.5 8.071 5.299 8.071 6.286Z" fill="#999EA3"></path> </svg> </g> <g id="i-facebook"> <svg xmlns="http://www.w3.org/2000/svg" viewbox="0 0 20 20"> <path d="M20 10C20 4.477 15.523 0 10 0C4.477 0 0 4.477 0 10C0 14.69 3.229 18.625 7.584 19.706V13.056H5.522V10H7.584V8.683C7.584 5.279 9.124 3.702 12.466 3.702C13.1 3.702 14.193 3.826 14.64 3.95V6.72C14.404 6.695 13.994 6.683 13.485 6.683C11.845 6.683 11.212 7.304 11.212 8.919V10H14.478L13.917 13.056H11.212V19.927C16.163 19.329 20 15.113 20 10Z" fill="#999EA3"></path> </svg> </g> </defs> </svg> </body></html>