====== Email Importer ======

//Email Importer// is a service that turns email into [[https://linear.app|Linear]] issues and
comments. It is built and operated by [[https://grandjean.net|Grandjean & Braverman, Inc.]] (G&B),
and it runs for more than one Linear workspace.

If you arrived here from a **Developer URL** on an OAuth application in your Linear workspace, this
page is the right place to start: it explains what that application is, why it has access, and who
to contact.

===== What it does =====

A Linear workspace using this service is given its own dedicated email subdomain --- something like
''acme.ccissue.com''. Every address at that subdomain belongs to the service, and mail sent to one of
them ends up in Linear:

  * Mail to a **team address** creates a new issue.
  * Mail to an **issue address** is added to that issue as a comment.
  * **Replies thread.** A reply to a message the service already knows about is added to the original issue as a comment rather than opening a second issue --- even if someone has changed the subject line mid-conversation.
  * **Closed issues are left closed.** Where a message is matched to an earlier issue by its subject alone, and that issue has since been completed or cancelled, a new issue is created instead of a comment being added to something nobody is watching.

The body of the message is converted to Linear's formatting, and attachments and inline images come
across with it. Nothing is discarded to make it fit.

===== The two address forms =====

Using ''acme.ccissue.com'' as the subdomain, and teams whose Linear keys are ''ABC'' and ''DEF'':

^ Address ^ What happens ^
| ''ABC@acme.ccissue.com'' | Creates a new issue in the ABC team, or adds a comment to an existing issue if the message is part of a conversation already tracked and that issue is still open. |
| ''DEF@acme.ccissue.com'' | The same, for the DEF team. Each team has its own address. |
| ''ABC-42@acme.ccissue.com'' | Adds a comment to issue ABC-42. |

Both forms are case-insensitive, and both the //To// and //Cc// fields are checked --- so a single
message can be copied to several issues at once.

Mail sent to a team key that does not exist in the workspace is not thrown away. It is filed into a
designated fallback team, so a typo in an address surfaces as a findable issue rather than silence.

Where it has been enabled, the sender of a message that creates a **new** issue gets a short
automatic reply carrying the issue's identifier and a link to it. Replying to that acknowledgement
adds a comment to the issue.

===== Who is allowed to send =====

This is usually the first question an administrator has, because an email address that creates
issues in your workspace is an inbound path from the open internet. Two separate checks apply, in
this order.

==== 1. The sender is authenticated ====

Before anything else, the service proves that the message really came from the domain in its
//From// header. A //From// header on its own is worth nothing --- anyone can put any address in
it --- so the service checks it the same way DMARC does, requiring either:

  * a valid **DKIM** signature whose domain lines up with the //From// domain, or
  * an **SPF** pass whose envelope sender lines up with the //From// domain.

Either one is enough; both must line up with the //From// domain to count. This is what stops an
outsider from mailing your workspace as one of your own staff.

If the check cannot be completed at all --- a DNS lookup fails, for instance --- the message is
**not** rejected. It is held and retried, so a temporary network problem never quietly loses
legitimate mail.

==== 2. The sender is authorised ====

Authentication establishes //who// sent the message. Authorisation decides whether that proven
sender is welcome. A sender is accepted if they match either of:

  * A **baseline list of domains** configured for the whole service --- normally the operating organisation's own domains.
  * A per-team **"Allowed Senders" document**, attached to that team in Linear.

The second of those is the one worth knowing about: it lets a team add an outside client or vendor
by editing a document in the Linear UI, with no involvement from G&B and no change to the service.
The two lists are additive --- matching either is enough.

==== How the two forms differ ====

^ Address ^ Authentication ^ Authorisation ^
| Team address (''ABC@...'') | Required | Required |
| Issue address (''ABC-42@...'') | Recorded, not enforced | Not applied |

Issue addresses are deliberately open. Knowing one is treated as the authorisation, because such an
address is only ever shared inside an existing conversation --- which is what lets an external
participant reply to a thread and have it land on the issue. The authentication result is still
recorded for every message, so an unverified comment can be traced afterwards.

Mail that fails these checks is rejected without a bounce message being sent back.

===== What the application does in your workspace =====

The OAuth application named **Email Importer** acts on the workspace on the service's behalf. In
normal operation it:

  * Creates issues and posts comments.
  * Uploads attachments and inline images from incoming mail.
  * Reads the workspace's teams and members, to route mail to the right team and to recognise senders.
  * Reads each team's "Allowed Senders" document, where one exists.
  * Reads the status of an issue matched to a message by its subject, so that a completed or cancelled issue does not quietly collect new mail.
  * **May assign a new issue** to the Linear member whose email address matches the sender, so mail from a colleague arrives already assigned to them. Anything assigned this way can be reassigned normally in Linear afterwards.

Everything the service produces is identifiable in the workspace, but the two kinds are labelled
differently:

  * An **issue** it creates is authored by the application, so its name is what appears.
  * A **comment** it posts is attributed to the person whose message it came from, shown as //their name and address// followed by //via// the application's name. Linear does not treat that person as the comment's account holder --- it is a label, and they need no Linear account for it.

A comment is only attributed this way when the sender was authenticated. On an issue address, where
authentication is recorded but not required, a message the service could not verify is attributed
to the application instead --- so a name on a comment is one the service proved, never one the
message merely claimed.

You can see and revoke it under **Settings → API → OAuth applications** in Linear. Revoking it stops
the service reaching that workspace, which means incoming mail to the subdomain stops becoming
issues and comments. Please get in touch before revoking it, so the mail flow can be shut off
cleanly rather than failing in place.

===== Each workspace is independent =====

Every workspace this service runs for has **its own OAuth application and its own credentials**. The
workspaces share nothing beyond the code that G&B operates: separate applications, separate
credentials, separate email subdomains, and separate issue data.

The practical consequence is that anything you do to your own application --- revoking it, rotating
its credentials, renaming it --- affects only your workspace. It cannot disturb anyone else's, and
theirs cannot disturb yours.

===== Support =====

The service is built, hosted and operated by **Grandjean & Braverman, Inc.**

For questions about this application, to report a problem with mail not arriving, or to arrange
changes to the addresses or sender lists, contact us through
[[https://grandjean.net|grandjean.net]].

If you are reporting a problem, it helps a great deal to include the **sender's address**, the
**address it was sent to**, and roughly **when** it was sent --- that is usually enough to trace a
single message end to end.