Docs / Files, mail, documents
For an author whose integration has to send a message, or start when one arrives.
Mail leaves and arrives through entities of your environment, exactly as HTTP calls do. An Email out account sends. An Email in mailbox is watched. A script never holds a password for either.
Sending
An Email out account carries the transport and nothing else you would call business logic. There are two:
- SMTP — a host, a port, whether the connection is encrypted, a username and a password.
- Microsoft Graph — a token URL, a client id, a client secret, a refresh token, and the address it sends from.
The password, the client secret and the refresh token are entered once and sealed. No screen, diff or recorded request gives one back, and no script can read one.
What a script writes is a call. Usually that is an email configured function,
which holds the envelope, the subject and a markdown body as a template — see
Connections and functions, which is where the
six function types live:
OrderReceipt({ to: input.event.body.customer, order: input.event.body.id });
return "receipt sent";For a message the shape of which is not worth configuring, sendMail takes the
whole message as a value. Either way the account decides the server and the
credentials, and an environment with exactly one account may be left unnamed;
one with several must be told which.
What an account does with a message
Building something that sends means running it, and running it means it sends. A sandbox wired to real addresses — a copied dataset, a test system holding real contacts — makes “check that it works” and “mail everybody” the same act. So every account says what it does with a message, and the same three choices exist in every environment:
deliver— the message goes to the people it is addressed to. The default, and what you eventually want.redirect— every recipient is replaced by the addresses configured on the account: To, Cc and Bcc alike, because Bcc is the one you forget. The message still carries who it was for, in its headers and in a marked subject line, and the body is untouched.record— nothing is sent at all. Each message is written into the run’s log with its recipients, its subject and as much of its text as a log line holds.
Work through them backwards. Build against record and read the run log — that
is the mode for the run that would mail a whole dataset, because redirecting
such a run only moves the flood into one inbox. Switch to redirect for the
handful of end-to-end proofs where you want to see a real message arrive. Turn
deliver on when the thing is meant to be real.
An account keeps its setting when it is promoted, deliberately: bring a new integration up redirecting, work the first glitches out where every message lands in one inbox, and turn sending on once it is right.
A send that was redirected or only recorded still succeeds. The run takes exactly the path it will take when the mail is real, which is the whole point. The answer says which of the three happened, so a script can branch on it, and the run log says it too — so you can see at a glance which of a run’s messages went anywhere. Wherever the account is named, an account that is not delivering says so.
Receiving
An Email in mailbox is a mailbox the environment watches. Configure it with a provider, the mailbox address, optionally a folder, and how often to look:
- Microsoft Graph — OAuth credentials: a token URL, a client id, a client secret and a refresh token.
- IMAP — a host, a port, whether the connection is encrypted, a username, and either a password or the same OAuth credentials.
A message that arrives becomes one run of every main script that listens, the same way a webhook does. Point a script at it with a trigger — see Triggers and concurrency.
Four behaviours worth knowing before you switch one on:
Activating a mailbox processes no history. The first look adopts a baseline: whatever is already in the mailbox is not work. Otherwise a mailbox with ten years of mail would become ten years of runs the moment somebody ticked Enabled.
A message becomes work at most once. The platform claims a message before it enqueues anything, so a crash costs that one message its run rather than delivering it twice.
A mailbox nobody listens to is not polled at all, and the run log says so rather than leaving you to wonder. Add the trigger, and it starts.
A broken mailbox complains once, when it breaks, and says so once more when it recovers — not on every pass.
What a message looks like to a script
A mailbox run arrives with input.event.kind of email_in and the message
envelope as its body — sender, recipients, subject, body and the descriptions
of any attachments. Reading what triggered you is the page
about input.event door by door.
One mailbox that is not yours
An installation also has a mail account of its own, which it uses to send invitations and password resets. It belongs to whoever runs the installation, not to a tenant, and nothing in your environment configures it or sends through it.