Welcome to MailSlick

MailSlick creates, manages and deploys email signatures. This guide covers everything in the app, in the order you are likely to need it.

Who does what

In most organisations only IT or the owner needs an account. Staff whose signatures are managed centrally do not need to sign in at all.

Two sides of the app

• My signatures is the personal designer: build a signature, preview it, copy it into your own mail app.
• Organisation (admins only) manages signatures for everyone from one place: an organisation template filled in from Microsoft 365, groups that change parts of it for some people, and individual changes for one person.

Finding this guide again

Open your account menu (top right, "Signed in as …") and choose Help & documentation. The guide opens in a new tab, so you can keep it beside the app.

Getting started

The first sign-in

On a brand-new installation the first visit shows Create the owner account. Choose your own name, email and a password of at least 10 characters. Any signatures already on the server (from before accounts existed) become yours.

After that, every visit shows Sign in. There is no public sign-up: new people are invited by the owner (see Accounts and admins).

The editor at a glance

+----------------------------------------------------------------------+
| MailSlick  [My signature v] [name]  * Saved   New  Duplicate  Copy & install  (You) |
+--------+-------------------------------+-----------------------------+
| Details|  Editing panel for the        |  Live preview               |
| Images |  selected tab                 |  Desktop / Phone            |
| Social |                               |  Light / Dark / Inverted    |
| Blocks |                               |                             |
| Design |                               |  The email as recipients    |
| Layouts|                               |  will see it                |
+--------+-------------------------------+-----------------------------+

• The tabs down the left side switch the editing panel.
• The preview on the right shows the exact HTML that will be copied, inside a mock email. It updates as you type.
• The save light next to the signature's name shows the state: green Saved, amber Unsaved changes (a save is moments away), red Not saved: retrying. Saving is automatic; there is no Save button.

Building your first signature, in order

1. Details: your name, job title, company, phone numbers, email, website and address. Anything you leave empty is simply left out of the signature.
2. Images: a photo (cropped to a circle, rounded square or square) and a company logo.
3. Social: the networks you want shown as icons.
4. Blocks: the sign-off above the signature ("Best regards," with an optional handwritten name) and anything below it: a button, a banner, a row of badges, a quote, a disclaimer.
5. Design: font, colours, size and spacing, dividers.
6. Layouts: pick one of eight arrangements. Switching keeps everything you have entered.
7. Copy & install: copy the finished signature and paste it into your mail app. See Installing a signature.

Your library

• New starts another signature from the example.
• Duplicate copies the current one, useful for a shorter reply signature.
• The drop-down at the top switches between your saved signatures; the box beside it renames the current one.
• Delete (the bin icon) removes the current signature after asking.
• Undo / Redo (the arrows, or Ctrl+Z / Ctrl+Y) step through your edits. Rapid edits such as dragging a slider count as one step.

Theme

The account menu has a Theme switch: Dark, Light or System. It is remembered in your browser. The email preview always keeps mail-app colours, whatever the editor's theme.

Designing a signature

Each tab of the editor, and what every control does.

Details

Person: full name, job title, department, company.

Contact: office phone, mobile, fax, website, email, address.

• Empty fields disappear. No blank lines, no stray separators. Fill in only what you want shown.
• Phone numbers are tidied for you. Type 4045550100 and, when you leave the box, it becomes (404) 555-0100. The Phone number style control under the phone fields chooses the format: (404) 555-0100, 404-555-0100, 404.555.0100, or As typed. Changing the style reformats every number in the signature. Numbers that are not a 10-digit North American number (an international number, a short number, text) are left exactly as typed. Extensions such as x23 are kept and written ext. 23.
• Website can be typed as example.com; the link becomes https://example.com and shows as example.com.

Custom fields: your own label and value, for things like office hours, a licence number or a booking link. Reorder with the arrows.

Images

Photo: upload a PNG, JPEG or GIF, or drop a file on the box. Choose the shape (circle, rounded, square), size, and an optional link. The shape is cut into the image itself, because classic Outlook cannot round corners.

Logo: upload the company logo and set its width. A PNG with a transparent background looks best, in dark mode too. With both a photo and a logo, most layouts put the logo under the details.

Uploads are scaled down before they are stored: a signature never shows an image wider than 600 px, so larger files are wasted on every email sent.

Social

Your profiles: add a network from the grid, paste the address, reorder or remove. Thirty networks are available, including Facebook, Instagram, LinkedIn, X, YouTube, TikTok, Threads, Bluesky, Mastodon, GitHub, WhatsApp, Telegram, Spotify, Calendly and Google reviews.

Icon style: shape (plain, circle, rounded, square), colour (each network's brand colour, your accent colour, grey or black), size and spacing. Icons are drawn as sharp images so they look the same in every mail app.

Blocks

Sign-off: the closing line above the signature.

• Space above the signature: blank space between your message and the signature. Set it here rather than with blank lines in Outlook, because Outlook removes typed blank lines when it saves a signature.
• Closing line: "Best regards," or your own words.
• Add a handwritten name: your name in one of eight script styles, drawn as an image. Handwritten text can be left empty to use your full name. Space between the closing line and the name sets the gap.

Below the signature: add any of these, reorder them with the arrows, and slide each one right with Move right.

Design

• Font: ten fonts that are already installed on readers' computers, so the text never falls back to a different font.
• Colours: eight ready palettes chosen to stay readable in dark mode, plus individual colours for the name, text, accent and links.
• Size and spacing: overall size, line height, and the gap between parts.
• Divider: the line between the image and the details (none, a thin line, or an accent-coloured one).
• Separator between contacts: |, •, / or a space.
• Contact labels: none, letters (P: E:) or words (Phone: Email:).

Layouts

Eight arrangements, each shown as a live thumbnail of your own signature:

Classic (image left, divider, details right) · Classic, image right · Stacked · Centred · Logo on top · Accent bar · Single row · Compact reply (text only, for replies and forwards).

Switching layout keeps all your content.

The preview

• Desktop / Phone: the phone view shrinks the email to fit a phone screen, as iPhone Mail and the Gmail app do, and says by how much ("Shown at 85%"). Below about 85% it suggests what would help: a narrower logo, a shorter disclaimer or the Stacked layout.
• Light / Dark, colours kept / Dark, colours inverted: how the signature looks in a normal inbox, in a dark inbox that keeps colours, and in one that inverts them (as Outlook.com and the Gmail apps can). Dark modes are approximations; each mail app adjusts colours its own way.
• Character count: Gmail refuses signatures over 10,000 characters of HTML. The count turns red if yours is over; shorten the disclaimer or remove a block.

Installing a signature

Click Copy & install at the top of the editor. The dialog has a tab for each mail app with the exact steps, and two buttons:

• Copy signature copies the formatted signature. This is the one to use: paste it into your mail app's signature box.
• Copy HTML source copies the raw code. Pasting that into Outlook or Gmail shows the code as text. It is only for tools that take HTML directly, and for the HTML-file option below.

Outlook (classic, for Windows)

1. Click Copy signature.
2. In Outlook, open File → Options → Mail → Signatures…
3. Click New, give it a name, click in the edit box and press Ctrl+V.
4. Under Choose default signature, pick it for new messages and for replies/forwards, then click OK.

To update later: select the signature in the same dialog, click in the box, press Ctrl+A then Ctrl+V, and click OK.

New Outlook and Outlook on the web

1. Click Copy signature.
2. Open Settings (the gear) and find Signatures. It is under Account; in some versions under Mail → Compose and reply.
3. Choose New signature, name it, click in the box and press Ctrl+V.
4. Set it as the default for new messages and replies, then Save.

Gmail

1. Click Copy signature.
2. In Gmail, open Settings (the gear) → See all settings → General.
3. Scroll to Signature, click Create new, name it, then paste into the box with Ctrl+V.
4. Pick it under Signature defaults, then click Save Changes at the bottom of the page.

Gmail refuses signatures over 10,000 characters; the editor's preview shows the count.

Apple Mail

1. Click Copy signature.
2. In Mail, open Mail → Settings → Signatures, pick the account and click +.
3. Untick Always match my default message font.
4. Click in the right-hand box, select its placeholder text and press ⌘V.

HTML file

For Thunderbird, or to place a file directly in classic Outlook's signatures folder (%APPDATA%\Microsoft\Signatures): Download .htm, or Copy HTML source.

Things that catch people out

Blank lines disappear in Outlook. Outlook's signature editor removes blank lines inside a signature when it saves. Do not add spacing by pressing Enter; use the Space above the signature and Space between the closing line and the name sliders on the Blocks tab, which are kept.

Rounded corners. Classic Outlook ignores rounded corners in HTML. MailSlick draws rounded buttons and round photos as images, so they look right everywhere.

Images are hosted, not embedded. Every image in the signature (photo, logo, icons, handwritten name) is loaded from the MailSlick server each time an email is opened. That is deliberate: embedding images makes Outlook turn them into attachments and Gmail refuse them. It means the server must be reachable from the internet (see For the server owner), and that a recipient whose mail app blocks images sees the text and links but not the pictures. Each image carries a description shown in that case.

Changing a signature later. A pasted signature is a copy. After you change it in MailSlick, copy and paste it again (Ctrl+A, Ctrl+V in the mail app's signature box). Organisation-wide deployment that keeps signatures current without pasting is being built; see Organisation.

Accounts, organisations and plans

Organisations

Every account belongs to an organisation. Creating an account from the public page (Get started free) makes you the owner of a new organisation; people you invite join it. Organisations are separate from one another: each has its own people, signatures, directory connection, template, add-in and activity log, and none can see another's.

Plans

• Free: the single-user designer. Everyone in the organisation designs and installs their own signatures.
• Premium: adds the Organisation area, the directory (Microsoft 365 or Google Workspace), groups and individual changes, server-built signatures, the Outlook add-in, the mail-flow script, Gmail delivery and work-account sign-in. It is a flat price a year by the size of the organisation (Team up to 25 people, Business up to 100, Company up to 500, Enterprise beyond), never a charge per person.

Premium is switched on by whoever runs this MailSlick (the site owner), from Organisations and plans… in their account menu, where they see each organisation's name, owner, number of people, directory and last activity, and can set a plan, an end date, the tier and its people limit, and a private note. When a directory has more people than the plan covers, everyone still syncs and the Directory dialog says so, so the organisation can move to the next size. They never see an organisation's signatures or directory. The change is written to the organisation's own activity log. Until then, the Organisation switch shows what Premium includes and how to ask for it.

Accounts and admins

Open your account menu (top right) and choose Accounts and admins… (owner only).

Inviting someone

1. Enter their email and, optionally, their name, and click Invite.
2. MailSlick emails them the invite (when the server sends email; see below) and shows the same invite link to you, in case they don't see the email or you'd rather send it another way.
3. The link works once and expires after 7 days. The person opens it, chooses a password, and is signed in.

Until they do, the list shows Invite pending; afterwards, Joined. New invite link makes a fresh link if the old one expired.

Forgotten passwords

On the sign-in screen, Email me a reset link sends a one-time link (valid 7 days) to the address typed in, if it has an account; the answer is the same either way, so the form can't be used to find out who has one. The owner can also click Reset link beside the person in Accounts and admins…, which emails the same kind of link and shows it.

If this MailSlick doesn't send email, the sign-in screen says to ask the owner, and the owner sends the link by hand.

If the owner forgets their password, whoever runs the server can make a reset link from the command line; see For the server owner.

Admins

Tick Admin beside someone who has joined. Admins see the Organisation switch at the top of the editor and can manage the organisation's signatures, groups, people and the Microsoft 365 connection. Untick it to take that away. The owner is always an admin.

Admins cannot invite people, reset passwords or make other admins; only the owner can.

Removing someone

The bin icon removes a person and their personal signatures after asking. Images in emails they already sent keep working.

Your own email and password

Change email… in the account menu asks for the new address and your password. It becomes your sign-in address and where invites, reset links and notices reach you. Change password… asks for your current password and a new one of at least 10 characters; changing it signs out every other browser where you were signed in. People who sign in with a work account have neither: their address and password are their Microsoft's or Google's.

Two-factor sign-in

Anyone can add a second step to their own sign-in: a 6-digit code from an authenticator app (Microsoft Authenticator, Google Authenticator, 1Password and others) asked for after the password. Someone who learns your password still cannot sign in.

Turning it on

1. Open your account menu and choose Two-factor sign-in…, then Set up.
2. In your authenticator app choose add an account and scan the QR code MailSlick shows. If you cannot scan, type the key shown beside it.
3. Enter the 6-digit code the app now shows and click Turn on.
4. MailSlick shows eight recovery codes. Copy or download them and keep them somewhere safe; they are not shown again. Each one signs you in once if you ever lose your phone.

From then on, signing in asks for your password, then a code. Codes change every 30 seconds; if yours is refused, check the time on your phone is set automatically.

Recovery codes: used instead of the app's code when the phone is lost. Each works once. New recovery codes in the same dialog makes a fresh set and cancels the old one.

Turning it off needs your password and a current code, so an open session on another device cannot do it alone.

Lost phone and no recovery codes: the owner can remove your two-factor from Accounts and admins… (the remove link beside Two-factor on). You then sign in with your password alone and can set it up again. If the owner is the one locked out, see For the server owner.

Six wrong codes lock that sign-in for 15 minutes.

Sign-in protection

Five wrong passwords for an account from one address lock sign-in from there for 15 minutes. Twenty wrong attempts from one address across any accounts do the same.

What staff can and cannot do

Staff design their own personal signatures and nothing else. They cannot see or change the organisation's template, groups or other people's signatures, and they cannot change their own managed signature: any such change goes through an admin.

Connecting Microsoft 365

Connecting lets MailSlick fill in everyone's name, title, department, phone numbers, address and photo from your Microsoft 365 directory, and keep them up to date. It reads the directory only. It never has access to anyone's email, and your email never passes through MailSlick.

Before you start

• You need a Global Administrator (or Privileged Role Administrator) of your Microsoft 365 to create the app registration and grant its permissions. Nothing else works without that.
• Hybrid organisations (Active Directory in the office, synced to Microsoft 365) connect the same way. MailSlick reads the copy that your AD sync puts in Microsoft 365, so a change made in AD appears after your next AD sync cycle and then MailSlick's next sync.
• Allow about 10 minutes for the whole thing.

Step 1: create the app registration in Microsoft

This gives MailSlick an identity in your Microsoft 365 and tells Microsoft what it may read.

1. Sign in to the Microsoft Entra admin center at https://entra.microsoft.com as a Global Administrator.

2. In the left menu go to Entra ID → App registrations and click New registration. (In older menus the path is Identity → Applications → App registrations.)

3. Fill in the form:

   • Name: MailSlick
   • Supported account types: Single tenant only (older wording: Accounts in this organizational directory only).
   • Redirect URI: leave empty.
   • Click Register.

4. You land on the app's Overview page. Two values here go into MailSlick; copy them somewhere safe:

   • Application (client) ID, a value like aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
   • Directory (tenant) ID, the same shape

5. In the left menu of the app, open API permissions, click Add a permission, choose Microsoft Graph, then Application permissions (not Delegated). In the search box find and tick:

   • User.Read.All: reads people's profiles and photos.
   • GroupMember.Read.All: reads which security groups people are in. Needed only for groups based on security groups; harmless otherwise.
   • Optionally Organization.Read.All, which lets MailSlick show your organisation's name. Not required.

   Click Add permissions.

6. Still on API permissions, click Grant admin consent for (your organisation) and confirm. The Status column should show a green tick and Granted for … on each permission. Without this step MailSlick is refused.

7. Open Certificates & secrets, then Client secrets → New client secret. Give it a description such as MailSlick and an expiry. Microsoft recommends 12 months or less; 24 months is the maximum. Click Add.

8. Copy the secret's Value immediately. It is shown only once. Do not copy the Secret ID beside it; that is a different thing and will not work.

Step 2: enter the details in MailSlick

1. In MailSlick, open your account menu and choose Microsoft 365 directory… (or, in the Organisation area, the Microsoft 365 directory line at the bottom left).
2. Paste the three values:
   • Directory (tenant) ID → from the Overview page
   • Application (client) ID → from the Overview page
   • Client secret → the Value from step 8
3. Click Save and test.

MailSlick stores the secret encrypted and never shows it again. The form checks the two IDs look right before sending anything, then signs in to Microsoft and reads one person to prove the permissions work.

If the light turns green ("Test passed"), the first sync starts automatically. If it turns red, the message says what is wrong in plain words; see the table below, fix it, and the form stays open for corrections.

What syncing does

• Sync now reads the whole directory. It also runs automatically every hour.
• Who is included: enabled member accounts with an email address. Left out: guests, disabled accounts, and accounts with no mailbox (rooms, equipment).
• What is read: name, job title, department, company, office phone, mobile, fax, office location, street, city, state, postal code, country, photo, and security-group membership (including membership through nested groups).
• Leavers: anyone the directory no longer lists is removed from MailSlick, along with any changes an admin made just for them.
• Photos come from Microsoft 365. People whose mailbox is still on an on-premises Exchange server may have no photo available; they simply get none.

Every sync, test and connection change is written to the Activity list at the bottom of the dialog, with who did it.

Keeping it working

• The client secret expires on the date you chose. When it does, the light turns red with "Microsoft rejected MailSlick's app secret. It may have expired." Make a new secret in Certificates & secrets, click Change details in MailSlick, paste the new Value (leave the IDs as they are) and Save and test.
• Test checks the connection at any time without changing anything.
• Disconnect forgets the directory and its people in MailSlick. Nothing changes in Microsoft 365, and photos already in sent emails keep working.

Messages and what to do

Organisation

The Organisation switch at the top of the editor (admins only) manages signatures for everyone from one place.

How a person's signature is worked out

Signatures are built in layers. Each layer changes only what differs from the one above it; everything else is inherited.

1. Organisation template: the base everyone shares. Layout, colours, fonts, logo, social links, sign-off, disclaimer and other blocks.
2. Group changes: for people matched by a rule (department, position or security group). For example a badges row for one role, or a different button for one department.
3. The person's own details from Microsoft 365: name, title, phones, photo and so on, wherever the template says they come from the directory.
4. Individual changes: anything set just for that one person, such as their own photo instead of the directory one.

Change the logo in the template and everyone gets it, except people whose group or own settings deliberately use another. That is the point of the layers.

Organisation template

The first visit asks you to create the template, starting from one of your own signatures or from the example. From the start, name, title, department, phones, fax, email, address and photo are set to come from each person's Microsoft 365 profile; the company name is shared, because directories often leave it blank.

Beside each detail on the Details tab is a Microsoft 365 switch:

• On: the box reads From each person's Microsoft 365 profile. Everyone gets their own value, and a person with no value for it (no fax, say) simply has that line left out.
• Off: what you type is shared by everyone.

On the Images tab, Use each person's Microsoft 365 photo does the same for the photo. When the name comes from the directory, so does the handwritten sign-off.

Preview as above the preview shows the template filled in for a real person. Switch between people to check it works for someone with every detail and someone with few.

Groups

Who is in a group comes from the directory, not from a list you keep by hand:

The values offered as you type come from the people already synced. Give the group a name, or it takes the value's name.

Priority. Groups are listed highest priority first. Someone who matches two groups gets the higher one only; group changes do not stack. Use the arrows to reorder.

Editing a group opens the normal editor, with two differences:

• A Changed here box lists exactly what this group changes, for example Blocks or Logo. Click the × on any item to go back to the inherited version. Nothing changed means everything is inherited.
• Details that come from Microsoft 365 are shown fixed, because the directory's value is applied after the group's changes and would win anyway. To give a particular person a different value, use their own page under People.

Preview as lists the group's members. Delete removes the group; its people go back to the organisation template.

People

Everyone from the directory, with their photo, title, which group they fall under, and whether they have own changes. Use the search box to find someone.

Open a person to see their real signature and make changes just for them: their own photo, a different mobile number, an extra badge. The same Changed here box shows what is theirs, and Remove all of (name)'s own changes at the top right returns them entirely to the inherited signature. A person's own values override the directory's.

Activity

Every change is recorded with who made it and what changed, for example Group "Litigation" changed: blocks or Organisation template changed: logo. The list is in the Microsoft 365 directory dialog.

Saving

Changes in the Organisation area save automatically a moment after you make them, and before you move to another group or person. The line at the bottom left says All changes saved, Saving…, or shows a red message if the server refused a change (it retries by itself).

Built on the server

Every person's signature is built on the server after any change: a template or group edit, someone's own change, or a directory sync that brings a new title or a new starter. Nobody's browser needs to be open; the scheduled sync at night rebuilds what changed by itself. The line under the search box in People shows how far it has got:

• 12 of 12 signatures up to date (green): everyone's signature matches the current layers and directory.
• Building signatures… 4 of 12 (amber): a rebuild is running; it usually takes under a second per person.
• Not built: … (red): the server could not build them, with the reason. Rebuild tries again.

The built signatures are what the Outlook add-in and the mail-flow rule send, so a change here reaches the next email with nobody pasting anything. Images in built signatures (logo, photo, icons, drawn buttons) are loaded from the server's public address; if the amber note says the address is not set, whoever runs the server should set SIGSTUDIO_PUBLIC_URL (see For the server owner).

What is not here yet

Delivering the built signatures into people's mailboxes automatically (an Outlook add-in deployed once by IT, so each new email carries the current signature with nothing to paste; Gmail signatures set directly) is the next stage of MailSlick and is not available yet. Until then, a person's current signature can be copied from their page and installed as any personal signature is.

Troubleshooting

Messages the app can show outside the Microsoft 365 dialog (those are listed under Connecting Microsoft 365), and common puzzles.

Signing in

The editor

In the mail app

Organisation area

For the server owner

How MailSlick runs, what it stores, and the few things only the person running the server can do.

What runs where

MailSlick is one container: a Python API that also serves the editor and the public page, plus a small Node render worker the API starts when it builds everyone's signature on the server (the same code the editor uses, so what the admin sees is what is built). It sits behind a reverse proxy (Traefik in the reference deployment) that provides HTTPS. The deployment files are in deploy/:

Settings

The data folder

Everything MailSlick stores is in the data folder (deploy/data on the host):

Deploying

deploy.ps1 packages the last commit, uploads it, and on the server builds the new version beside the running one, starts it in a throwaway container and checks it answers before switching over. If the new version is unhealthy after the switch, it rolls back to the previous image. It refuses to deploy while anyone is using the site (any request in the last two minutes); -Force overrides that. It runs in its own window and closes itself after a successful deploy.

The first deploy with -WithData copies a laptop's data folder to the server, but only if the server has no data yet; it never overwrites.

Backups

• backup.sh runs daily at 03:15 (installed in cron by the deploy). It takes a consistent copy of the database and all images into /opt/mailslick/backups/mailslick-<date>.tar.gz and keeps 14 days.
• The encryption key is deliberately not in the backup, so a copied backup cannot unlock the stored client secret. After restoring onto a new server, MailSlick makes a fresh key; the Microsoft 365 light turns red with "Enter the client secret again", and an admin pastes the client secret's Value once more. Everything else restores completely.
• restore-test.sh unpacks the newest backup into a scratch folder, starts a separate throwaway MailSlick on it, compares what it holds with the live data and prints RESTORE OK. Run it now and then to prove backups work.
• Copying backups off the server is the owner's responsibility; the script leaves them in place.

The site owner

The account made on the setup screen of a fresh installation is the site owner: the owner of its own organisation like anyone else, plus Organisations and plans… and the early-access requests in the account menu. An installation from before organisations existed is adopted on first start: its people become one Premium organisation and its owner becomes the site owner.

Owner commands

Run inside the container with docker exec mailslick python -m app.admin …:

Updating the Microsoft client secret

Nothing to do on the server. Admins paste a new secret in the app (see Connecting Microsoft 365); it is stored encrypted with the app's key.

Health

The container has a health check (/api/auth/state every 30 seconds). docker ps shows healthy. Logs: docker logs mailslick.

Outlook add-in

The add-in puts each person's current signature into every new message, reply and forward as they start writing. An administrator deploys it once from the Microsoft 365 admin center; nobody installs or pastes anything, and a template change in MailSlick reaches the next email within a minute.

It works in Outlook on the web, new Outlook for Windows, classic Outlook for Windows (Microsoft 365 builds on Windows 10 1903 or later), Outlook for Mac, and Outlook on iOS and Android.

How it identifies people

When Outlook starts a message, the add-in asks Outlook for a Microsoft sign-in token for the person using it, issued against your organisation's app registration (the one from Connecting Microsoft 365). MailSlick checks that token against Microsoft's signing keys and that it is for your registration and your tenant, then looks the person up by their Microsoft id in the synced directory. Nothing self-declared is trusted, and the add-in reads nothing from the email itself.

Before you start

• Microsoft 365 is connected and synced, and the organisation template is set up, so signatures are built (the People list says N of N signatures up to date).
• The server has its public address set (SIGSTUDIO_PUBLIC_URL); the add-in loads from it.
• You are a Global Administrator, or have both an Entra application administrator and a Microsoft 365 global administrator at hand: step 1 is in Entra, step 2 in the admin center.

Step 1: let the add-in sign people in (Entra, once)

In the Microsoft Entra admin center, open App registrations and the MailSlick registration you made for the directory connection.

1. Authentication → Add a platform → Single-page application. Redirect URI: brk-multihub:// followed by the server's host, e.g. brk-multihub://mailslick.example.com (no https://, no path). Save. This tells Microsoft that Outlook may obtain tokens on the add-in's behalf.
2. API permissions → Add a permission → Microsoft Graph → Delegated permissions, tick User.Read (the sign-in permission), Add permissions, then Grant admin consent for (your organisation). Without consent, people would be asked to consent one by one on first use. The Application permissions already there stay as they are.

Step 2: deploy the add-in (Microsoft 365 admin center, once)

1. In MailSlick, open Microsoft 365 directory… and click Download manifest in the Outlook add-in box. It saves mailslick-outlook.xml.
2. In the Microsoft 365 admin center go to Settings → Integrated apps → Upload custom apps.
3. Choose Office Add-in, Upload manifest file, and pick the downloaded file. Click Next.
4. Choose who gets it: a pilot group first (Specific users/groups), then everyone. Click Next, accept, Finish deployment.

The add-in appears in Outlook within a few hours (Microsoft's figure is up to 24; a restart of Outlook helps). Deploying again with the same manifest updates it rather than adding a second copy.

What people see

Nothing, mostly: the signature is there when they start an email. In the ribbon of a new message there is a MailSlick → My signature button that shows the current signature and inserts it again if it was deleted.

The first time, Outlook on some platforms asks the person to sign in once (a small notice MailSlick needs you to sign in once… with an Open MailSlick link). After that it is silent.

The Outlook add-in box in the Microsoft 365 dialog shows how many times signatures have been fetched and when the add-in was last seen, so you can tell it is working before anyone reports back.

Messages people might see

Replies and forwards

Replies and forwards currently get the same signature as new messages. A shorter reply signature per organisation is planned.

Mail-flow rules, for devices without the add-in

Phones with other mail apps, shared mailboxes and anything else that cannot run the add-in can still get signatures from Exchange itself: a mail-flow rule per person that appends their signature to every message they send. Microsoft offers no API for these rules, so MailSlick writes the PowerShell and an Exchange administrator runs it.

1. In the Outlook add-in box of the Microsoft 365 dialog, click Mail-flow script. It saves mailslick-mail-flow.ps1 with everyone's current signature in it.
2. On a machine with PowerShell, once: Install-Module ExchangeOnlineManagement.
3. Run the script as an Exchange administrator. It signs in, then creates or updates one rule per person, named MailSlick signature: (email). Run it again after signature changes; it replaces the rules in place.

What to know before choosing this:

• The signature lands at the very bottom of the message, below any quoted reply, because that is where Exchange appends. The add-in puts it where a signature belongs. Use the rules only where the add-in cannot run.
• No double signatures. Messages the add-in already signed carry a header the rules skip, so people with both get one signature.
• Exchange limits. A disclaimer holds 5,000 characters and an organisation 300 rules. The script's header lists anyone left out and why; shorten their signature (a smaller disclaimer block, fewer blocks) and download again.
• To remove every rule MailSlick made, the script's header has the one-line command.

The organisation's logo

Emails already sent keep pointing at the images they were sent with. So that an old email shows the current logo, built signatures load the logo from a fixed address (/logo/<organisation>.png) that always serves whatever the organisation template's logo is now. Changing the logo in the template changes it in every email, old and new, the next time it is opened.

Connecting Google Workspace

Connecting lets MailSlick fill in everyone's name, title, department, phone numbers, address and photo from your Google Workspace directory, keep them up to date, and write each person's signature straight into their Gmail settings. Nothing to install and nothing to paste: Gmail is the one platform where that is possible. MailSlick never reads anyone's mail.

What MailSlick is allowed to do

Access is a service account you create in your own Google Cloud project, which a Workspace super admin authorises once for exactly three scopes:

No scope that reads, sends or alters mail is requested, and the authorisation screen lists only these three.

Before you start

• A Google Workspace super admin (or a role with security and API-control rights) to authorise the service account, and their email address.
• Access to the Google Cloud console (console.cloud.google.com) with the same Google account. It is free; nothing here costs anything.
• Allow about 15 minutes.

Step 1: make a project and turn on the two APIs

1. Open the Google Cloud console and create a new project (the project picker at the top → New project), named for example MailSlick.
2. With that project selected, go to APIs & Services → Library. Search for and Enable:
   • Admin SDK API (reads the directory)
   • Gmail API (sets signatures)

Step 2: create the service account and its key

1. Go to APIs & Services → Credentials → Create credentials → Service account. Name it MailSlick, click Create and continue, skip the optional role and user steps, Done.
2. Open the new service account, then its Keys tab → Add key → Create new key → JSON → Create. A .json file downloads. Keep it safe; it is the account's password. You will upload it to MailSlick in step 4, and MailSlick stores it encrypted.
3. On the service account's Details tab, copy the Unique ID (a long number). It is also the client_id inside the JSON file.

Step 3: authorise it for your Workspace (super admin)

1. Open the Google Admin console (admin.google.com) → Security → Access and data control → API controls → Manage Domain Wide Delegation.

2. Add new. Paste the Unique ID from step 2.3 as the Client ID, and these three scopes, comma-separated, in the OAuth scopes box:

   https://www.googleapis.com/auth/admin.directory.user.readonly,
   https://www.googleapis.com/auth/admin.directory.group.readonly,
   https://www.googleapis.com/auth/gmail.settings.basic
   

3. Authorize. Changes can take a few minutes to apply.

Step 4: enter the details in MailSlick

1. In MailSlick, open your account menu and choose Directory…, then Google Workspace.
2. Enter the super admin's email address (MailSlick reads the directory as this person) and upload the JSON key file from step 2.2.
3. Click Save and test.

If the light turns green ("Test passed"), the first sync starts. If red, the message says what is wrong; see the table below.

What happens after that

• Sync reads everyone every hour (and on Sync now): active users with a primary address; suspended and archived accounts are left out. Details come from the person's organisation entry (title, department, company), phones (work, mobile, fax) and work address; photos from their profile; groups from Google Groups.
• Signatures are written into Gmail after every rebuild: when the template, a group, a person's own changes or the directory changes, the affected people's signatures are set on their primary send-as address within a minute. The People list says N of N signatures up to date · N in Gmail; anyone Gmail refused is listed with the reason, and the next rebuild tries again.
• Gmail shows the signature exactly as built, images loaded from the MailSlick server. Gmail's own limit is 10,000 characters; the editor shows the count.

Messages and what to do

Sign in with a work account

People in a connected directory can sign in to MailSlick with their Microsoft 365 or Google Workspace account instead of a MailSlick password: on the sign-in screen, Use your work account, then their work email. They land on their own page: My signature (the organisation signature built for them, with Copy) and their personal signatures. They never become admins by signing in; the owner grants that in Accounts and admins… as for anyone else.

Staff don't need this to receive signatures: the Outlook add-in and Gmail delivery identify people through Microsoft and Google directly. It is for people who want to see their signature or design personal ones.

How it works

MailSlick finds the organisation from the email's domain and sends the browser to that organisation's identity provider. The token that comes back is checked against the provider's signing keys, the organisation's registration, and the sign-in's own nonce; the person is the directory entry with that provider id. Two-factor for these accounts is the provider's (Microsoft's or Google's) and MailSlick's own two-factor doesn't apply to them.

Microsoft 365: one step in the app registration

Open the organisation's MailSlick app registration in the Entra admin center (the one from Connecting Microsoft 365):

1. Authentication → Add a platform → Web. Redirect URI: the server's address followed by /api/auth/microsoft/callback, for example https://mailslick.example.com/api/auth/microsoft/callback. Save.
2. Nothing else. Sign-in uses the openid, profile and email scopes, which every registration has, and the client secret already saved in MailSlick. If you granted admin consent for User.Read when deploying the add-in, people see no consent prompt; otherwise each sees a one-time "permissions requested" screen listing only sign-in and profile.

Google Workspace: one OAuth client for the server (site owner)

Google sign-in uses one OAuth client for the whole MailSlick, made by whoever runs the server, because Google ties sign-in to the Cloud project it was created in. Workspace organisations then need nothing of their own: MailSlick checks that the signed-in account's domain is the connected one.

1. In the Google Cloud console (any project you own), APIs & Services → OAuth consent screen: External, app name MailSlick, your support email, and the server's domain under authorised domains. Publish it (or keep it in testing with your own accounts while trying it).
2. Credentials → Create credentials → OAuth client ID → Web application. Authorised redirect URI: the server's address followed by /api/auth/google/callback. Create, and copy the Client ID and Client secret.
3. On the server, put them in .env as GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET and redeploy. The sign-in screen offers Google as soon as a Workspace is connected.

Messages

Billing with Stripe

Premium is paid through Stripe: a customer picks a size tier, pays on Stripe's hosted page (card details never touch MailSlick), and Stripe tells MailSlick to switch the organisation on, renew it, or drop it to Free when a card finally fails or they cancel. The site owner sets it up once in Billing setup…; plans switched by hand in Organisations and plans… keep working alongside.

Setting it up (site owner, about 20 minutes)

Do it first in Stripe's test mode (the toggle at the top of the Stripe dashboard), try a purchase with Stripe's test card 4242 4242 4242 4242, then repeat the steps in live mode with live keys.

1. Products. In Stripe → Product catalogue → Add product, make one product per tier: MailSlick Team, MailSlick Business, MailSlick Company. For each, one recurring, yearly price (the amounts on the public page). Open each price and copy its Price ID (price_…).

2. Secret key. Developers → API keys → Secret key (sk_test_… or sk_live_…). Copy it.

3. In MailSlick: account menu → Billing setup…. Paste the secret key and the three price ids, Save and test. The light turns green and lists the plans as Stripe has them; it stays amber until step 4.

4. Webhook. Copy the webhook address shown in Billing setup. In Stripe → Developers → Webhooks → Add endpoint, paste it, and select these events:

   • checkout.session.completed
   • customer.subscription.created, customer.subscription.updated, customer.subscription.deleted
   • invoice.payment_failed

   After adding, open the endpoint and copy its Signing secret (whsec_…) into Billing setup, Save and test. Green.

5. Customer portal (optional but recommended): Stripe → Settings → Billing → Customer portal: allow customers to update payment methods, see invoices and cancel. MailSlick's Billing… menu item opens it.

Keys are stored encrypted on the server and never shown again; Test re-reads the prices at any time. To rotate a key, paste the new one and Save and test.

What customers see

• A free organisation's Organisation tab shows the plans with prices and a Choose button per tier (only when billing is set up; otherwise it says to get in touch).
• Choose opens Stripe Checkout. On payment they return to MailSlick already on Premium with the tier's people limit, and the activity log says so. The owner gets an email.
• Billing… in the account menu opens Stripe's portal for the card, invoices and cancelling.
• A failed renewal: Stripe retries over its schedule and emails the card holder; Premium continues until the paid period ends. If Stripe gives up, the organisation drops to Free and the owner is emailed.

Mixing with plans set by hand

Organisations and plans… still works. An organisation on a hand-set Premium with no end date stays Premium whatever Stripe says (useful for a comped customer or an invoice paid outside Stripe). Rows paid through Stripe show Stripe with the subscription status.

Messages