Installation and Account Setup
To create an account, you first need to install the Mailscript CLI. The CLI is where you:
- Manage accounts.
- Claim addresses.
- Create keys for your addresses.
- Create workflows for your automations.
- Add triggers for your workflows.
- Add actions for your workflows.
- And more.
The first step is to download and install the executable.
Install the CLI executable
Install the CLI executable from the npm registry: mailscript with
yarn global add mailscript
or
npm install -g mailscript
Account setup
The next step is to initialize an account. The CLI uses a variety of identity providers, so choose the one you prefer.
mailscript login
Offline support
The CLI offers a secondary login flow for setups without access to a browser instance (eg. a docker container). It will have ask you to go over a login flow elsewhere and return a code to resume the sign-in process within the CLI context.
mailscript login --offline
Initialize
If this is the first time you are signing in you'll be prompted to pick a username. Once the you've has selected a username your account setup will be complete.
Addresses
Addresses
allow you to send and receive email messages. You receive a top level domain address corresponding to your selected username (eg. username@mailscript.com) and you can create addresses using your username as a first level subdomain (eg. team@username.mailscript.com)
You can create an address
easily:
mailscript addresses:add --address address@username.mailscript.com
Keys
Keys
allow you to share scoped access (write and/or read) to addresses you control with other people. Whenever you add an address a key is generated with full access for you.
You can list the keys for any address you control with the following command:
mailscript keys:list --address [your email address]
SMTP gateway
Keys
with the write access can be used to setup smtp
access to allow email clients to send messages from any mailscript address.
To do so use the following configuration:
host: smtp.mailscript.com
port: 465
user: full address (eg. username@mailscript.com)
pass: a key corresponding to the address with write access
Next, you can start setting up workflows whenever your addresses receive an email message.
Workflows
Workflows allow you to setup automations when a message arrives at any of the addresses you control. A workflow consists of a trigger and an action. Whenever a trigger is met the corresponding actions will be executed.
Triggers
Currently mailscript allows you to set up triggers based on incoming messages to addresses you control. You can set criteria to filter specific messages to trigger actions (e.g. messages sent from a specific address, messages that include attachments, that contain specific words in the subject or body, messages that contain attachments, mailscript even allows you to set up filters matching specific headers in your email message).
Triggers can be composed together to form new named triggers, allowing for the combination of criteria. See the Composing Triggers section for details.
Setting up Triggers
A trigger encapsulates criteria that can be used to test an incoming email. A trigger has a name and one or more criteria tests, these can include:
--from
: the from address equals the given value--sentto
: the address the incoming email has been sent to--hasthewords
: the email body contains the text specified e.g. 'alert'--domain
: the incoming email has afrom
address with the passed domain--subjectcontains
: the email subject contains the text specified--hasattachments
: the email has one or more attachments
To setup a trigger at the command line, provide a name and one or more criteria tests (replacing <username>
):
mailscript triggers:add \
--name example-trigger \
--from notifications@github.com \
--sentto github@<username>.mailscript.com \
--hasthewords build failed \
--domain github.com \
--subjectcontains PR \
--hasattachments
Composing Triggers
Triggers allow you to name a criteria that can be used to filter incoming emails. Triggers can be logically composed to create new triggers, allowing for the sharing of complex conditional logic.
Two or more triggers can be composed together using either and
or or
logic:
- and - every criteria must be met for the composing trigger to be met
- or - one criteria from the
or
list must be met for the composing trigger to be met
Assuming the following two triggers have been setup:
mailscript triggers:add \
--name alert \
--subjectcontains alert
mailscript triggers:add \
--name error \
--subjectcontains error
We can create a new trigger that would pass if the subject contains either 'alert' or 'error' with the command:
mailscript triggers:add \
--name alert-or-error \
--or alert \
--or error
If and
logic was required (an email with a subject that contains alert
AND error
e.g. alert: error in process
), the trigger composition would be:
mailscript triggers:add \
--name alert-or-error \
--and alert \
--and error
Actions
Mailscript offers automation outputs based on three different kinds of actions that can happen when a trigger is met:
- Email actions: send a new email message, forward the received email message, redirect the message to another address and reply to the sender or all participants in the received message.
- SMS action: send an sms text to a specified number.
- Webhook action: send a request to an http endpoint. The request can be customized to suit your needs (eg. customize verbs, headers and payload; you can even use data from the received message into the delivered payload).
Actions can be combined together to create a new named action; for instance, if you want an SMS to be sent and a webhook to post to discord on receiving an email at support@mycompany.mailscript.com
, you can create two separate named triggers for sms and webhook and a third combined trigger that does both.
Setting up Actions
Email actions of all types can be created at the command line and through the api.
All actions have a name, but they will have action type specific configuration options.
Email Actions
There are multiple email actions that can be setup to occur in response to an incoming email:
- forward - forward an email onto a new address as your email client would forward
- alias - redirect an email coming into the mailscript address to an external address, creating the effect that the email came from the originating address directly to the external address
- send - send a completely new email on to an external address (with the option to take parts of the triggering email over e.g. subject line)
- reply - respond to the incoming email, as if from the mailscript address that was sent to
- reply all - similar to reply but the response email is sent to everyong on the
cc
list as well
Forward
To create a forward action at the command line (replacing <username>
):
mailscript actions:add \
--name forward-to-alice \
--forward alice@example.com \
--from <username>@mailscript.com
The forward
parameter indicates the email address to forward on to. The from
parameter indicates which mailscript email address the relayed email will use for its from
field.
Alias
To create an alias action at the command line:
mailscript actions:add \
--name alias-to-personal \
--alias myaccount@gmail.com
The alias
specifies the email address the incoming email will be sent on to. You must verify that you control the email address. If you have not previously verified the email address, the mailscript cli
will guide you through verification when you add the alias action.
Send
To send on an email with subject and body you specify, you can create a send alias at the command line (replacing <username>
):
mailscript actions:add \
--name send-test \
--send jane@example.com \
--from <username>@mailscript.com \
--subject "Important: {{msg.subject}}" \
--text "Please check discord for more information."
Send creates a bespoke email as specified and sends it to the email address passed as the send
parameter. The from
parameter indicates the mailscript address to use for the from
field.
The subject line of the email is specified by the subject
parameter, and has access to the string interpolation variables (i.e. {{msg.subject}}
, {{msg.text}}
, {{msg.html}}
).
The body of the email must be specified, and can be passed either as plain test with --text
or as html with --html
.
Reply
A reply action responds back with an email to the incoming email. to create a reply action at the command line (replacing <username>
):
mailscript actions:add \
--name reply-test \
--reply \
--from <username>@mailscript.com \
--text 'Out of office'
The reply
indicates the type of action. Text or html must be specified to be prepended to the body of the reply email, using the --text
or --html
parameters respectively.
Reply All
A reply all action responds back with an email to the from
address of the incoming email and to everyone in the cc
list as well. To create a reply all
action at the command line (replacing <username>
):
mailscript actions:add \
--name replyall-test \
--replyall \
--from <username>@mailscript.com \
--text 'Out of office'
The replyall
indicates the type of action. Text or html must be specified to be prepended to the body of the reply email, using the --text
or --html
parameters respectively.
SMS Action
To send an SMS message in response to an incoming message, setup an SMS action at the command line:
mailscript actions:add \
--name sms-example \
--sms +447747111111 \
--text 'Important: {{msg.subject}}'
The phone number is provided with the sms
parameters (include the international dialling code). Mailscript will ask you to verify the phone number if you have not already done so. The text
parameter specifies the contents of the text and can include
interpolation variables derieved from teh incoming email (e.g. {{msg.subject}}
,{{msg.text}}
).
Webhook Action
To send an webhook in response to an incoming message, setup a Webhook action at the command line (replacing <webhook-url>
):
mailscript actions:add \
--name webhook-example \
--webhook <webhook-url>
The url endpoint that will be posted
to is given by the webhook
parameter. There are three optional parameters:
--body
the path to a file that will be passed as the body, variable interpolation is available within this file e.g.{{msg.subject}}
will substitute the incoming emails subject line.--method
to override the http method from the defaultPOST
--headers
the path to a file of valid json that will be passed as the headers of the webhook
Creating combined actions
We can combine two or more named actions into a new action with the combine command:
mailscript actions:combine \
--name forward-and-sms \
--action forward-to-alice \
--action sms-example
The combined forward-and-sms
action can be used when setting up
a workflow, and all subactions will be executed.
Daemon
The Mailscript cli allows you to use your local machine, or a server, as an output for an action in a workflow.
Using the mailscript daemon
command you can run a local daemon that will execute a script you specify as part of a workflow
and in response to an email.
Setting up a daemon
First register a new daemon action:
mailscript actions:add --name "action name" --daemon "daemon name"
We can now include the daemon in a workflow:
mailscript workflows:add \
--name "workflow name" \
--trigger "trigger name" \
--action "daemon name"
Any email sent to the input and that matches the trigger, will be forwarded to the daemon listening on the daemon name
action. To setup such a daemon run:
mailscript daemon \
--daemon "daemon name"
--command "cowsay \$subject"
The command parameter specifies the shell script to run when the workflow sends an email to the daemon action, in this case the cowsay
utility. The contents of the email are made available through the $subject
and $text
environment variables. The command will be executed each time on each received email.