Quickstart

Your support@ inbox in GitHub

Five steps. Four of them are about five minutes of clicking. The fifth is a DNS change at your registrar, and we are not going to put a number on that one — see step 3, which is the only step that can go wrong quietly.

Before you start

A GitHub repository you can install an app on — your own, or one in an org where you can approve installs.
A domain you control, and access to its DNS. This is the hard prerequisite: gitmail receives mail on your domain or not at all, so a @gmail.com address cannot be the thing you point at us. If you cannot add a DNS record somewhere, stop here — the rest will not work.
An email account to send the first test message from. Any one will do.

What you have at the end: an email to support@ your domain becomes an issue in your repo, and your reply — sent from the gitmail dashboard, from your verified domain or a shared gitmail address until verification is complete — is delivered and mirrored onto that issue as a comment.

Sign in

30 seconds with GitHub, longer by email

Two ways in: Continue with GitHub, or type your email and press Send magic link to get a sign-in link. Signing in with GitHub grants no access to your repositories — that is a separate install, in step 2.

The 30 seconds is the GitHub path, and it is the fastest thing on this page. The email path costs an inbox round-trip: you wait for the link to arrive, on your mail provider’s clock rather than ours, so budget minutes rather than seconds for it.

The two are not interchangeable further down. A project is a GitHub repo, so if you come in by email you are asked to connect a GitHub account partway through step 2 before you can link one. The login page says so under the email field. Coming in with Continue with GitHub skips that detour.

There is no signup form and no password. The magic link does not sign you in by itself: it opens one page headed One click away with a single Sign me in button, and pressing that lands you on the dashboard. The second button is the sign-in, not a failure — the link stays inert until a human clicks, so a scanner that opens your mail before you do cannot burn it. Continue with GitHub goes to the dashboard directly.

kontacts.dev/login

Link a repo

1 minute, plus a GitHub connect if you signed in by email

Press Add project. A project in gitmail is a GitHub repository — that is the unit everything else hangs off, so this step is not optional.

If you signed in by email, the panel opens headed Connect your GitHub account: gitmail cannot see any repositories yet, because nothing has told it who you are on GitHub. Press Connect GitHub, authorise gitmail, and you are brought back here with the panel reopened. This keeps the account you already have — same email, same workspace — and adds GitHub as a second way to sign in. If you came in with GitHub, you never see this screen.

The panel then reads Connect to GitHub. Press Install gitmail on GitHub → — it opens GitHub in a new tab and leaves gitmail sitting where it was. You can limit the install to a single repository, and we recommend you do on the first pass.

GitHub will ask for write access to issues

The install screen says Read and write access to issues. That is not a mistake and it is not more than we need — opening an issue from your mail is the product, and GitHub has no narrower permission for it. gitmail also reads repository metadata and your account email address.

It asks for nothing else. Your code, your commit history and your Actions secrets are not in the grant, and gitmail cannot push.

GitHub does not send you back, so switch to the tab you started in and press I've installed it — continue. Pick your repo, give the project a name, done.

Connect a domain

2 minutes, then a wait you don't control

Go to Settings → Domains, type a hostname you control and press Connect domain. To receive mail you must use your own domain — there is no ready-made gitmail inbox to borrow.

Ignore the placeholder — type a subdomain

The field suggests example.com, an apex. Enter mail.yourdomain.com instead, unless you really want gitmail to receive all mail for the domain. The MX record we give you replaces whatever is on that hostname today — at your apex, that means every existing address stops delivering where it used to. A subdomain leaves your apex untouched.

gitmail then shows the DNS records for that hostname, above two tabs: Receive everything, which routes every address on the domain you connected, and Selected subdomains, which leaves the apex alone and registers only subdomains you name. If you connected a subdomain as advised, the first tab is already the safe one and you can leave it be.

Copy each record into your registrar, then come back and press Check verification. The badge tells you where you are: Awaiting verification → Verifying → Verified, or Verification failed.

“Partly verified” is a stop, not a stage

The badge can also read Partly verified — 2 of 4 records live. Records verify one at a time, and this is where a real setup usually gets stuck: a copied value with a trailing dot, a registrar that appended your domain to a name that was already fully-qualified, a TTL that has not rolled over.

Do not move on from here. A partly-verified domain can already receive mail while every reply you try to send fails. The table names the record that is still missing — fix that one, press Check verification again, and repeat until the badge reads Verified.

This is the step we cannot time for you. Most registrars publish within minutes; a wrong record never publishes at all, and nothing will come and tell you. Press the button rather than wait for the page to change on its own.

Turn on issue creation

10 seconds

Go to Settings → Routing and switch on GitHub issues from inbound mail for your domain. It is off by default, and until you flip it, mail is stored in your gitmail inbox and no issue is opened. This is the step people skip and then conclude the product is broken.

If that page says “No verified domain yet”, you are early, not broken. The switch does not exist until step 3 shows Verified. Finish the DNS, come back, and it will be here.

Read this before you flip it

With the switch on, a message opens an issue when it arrives at an address you have declared on that domain. support@ is declared for you the moment the domain verifies; anything else — sales@, a harvested string — is stored in your gitmail inbox and opens nothing until you add it under Settings → Routing. Mail whose sender fails SPF, DKIM or DMARC is held there too. That gate checks who sent the message, not what it says: gitmail does not filter spam by content, so a sender who is who they claim to be still opens an issue. If your repository is public, so is anything that gets through.

This is why we tell you to start on a fresh subdomain that has never been published anywhere. Point support@ at it once you have seen the loop work.

Send the first email

30 seconds

From any mail account, send a message to support@mail.yourdomain.com. Delivery is by domain, so support@, hello@ and anything-you-like@ all land in the same project inbox. Nothing bounces for being the wrong address.

The message shows up in the dashboard, and it opens an issue in your linked repo when it arrived at a declared address — support@ is declared for you when the domain verifies, which is why that is the one to test with. That is the inbound half, and it is the half this page is named after.

To answer, reply from the gitmail inbox, not from the GitHub issue — a comment you type on GitHub emails nobody. Your reply is delivered and mirrored onto the issue as a comment, so the thread stays readable to your team.

Where your reply comes from depends on verification

Once mail.yourdomain.com is fully verified for sending, replies leave from that address. Your customer's Reply will reach your project inbox either way — shared-domain replies are now routed back to the right project.

Until verification is complete — or if your domain shows Partly verified (which blocks sends entirely) — replies go out from a shared address like acme-support-a1b2c3@kontacts.dev. Verification is the switch that changes this.

What we have not built yet

gitmail is in beta and we would rather you read this here than find it out on your own repo.

Sends fall back to the shared gitmail address until your domain is fully verified. Receiving always uses your custom domain. Outbound uses it too, once all DNS records clear. If your domain is only Partly verified, replies leave from a per-project address on the shared gitmail domain and that state blocks sends entirely. Once verification clears, sends switch over automatically. A customer reply reaches your project inbox in either case.
Commenting on the GitHub issue sends no email. The bridge is one-way there. Answer from the gitmail dashboard; the comment on the issue is a copy for your team, not the delivery mechanism.
No content-based spam filtering. Inbound mail is checked for sender authentication — SPF, DKIM and DMARC — and anything that fails is held in your inbox rather than published. But gitmail does not filter spam by content: on a routed domain with the switch on, a sender who authenticates their own domain gets published to your repo whatever they wrote.
Verification can stall without telling you. If one DNS record is wrong, the domain simply stays unverified — there is no alert, and a half-verified domain can receive mail while every reply fails. Press Check verification and read which record is still missing.
10 outbound emails per day. Replies you send from gitmail are capped at 10 per account per day. Receiving is not capped.
No uptime commitment. There is no status page and no SLO. This is a free beta and we do not yet promise your mail will always get through.

Stuck on a step, or found one that does not match what you see? Write to support@kontacts.dev — it reaches the people who build gitmail, and it is where this page gets fixed. Help says what to put in the message.

Start at step 1

Free while gitmail is in beta. No card, no checkout — there is nothing to buy yet.