Setup

In the AWS account

Not needed: Lambda, EC2, a VPC or a WorkMail organisation.

The short way: CloudFormation

Bucket, bucket policy, IAM user with policy, the device boundary and the SES receipt rule are created by a template (deploy/README.md in the repository says what each resource is for):

aws cloudformation create-stack \
  --stack-name s3mail \
  --template-body file://deploy/s3mail.json \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameters \
      ParameterKey=MailDomain,ParameterValue=example.org \
      ParameterKey=MailboxLocalPart,ParameterValue=info \
      ParameterKey=MailBucket,ParameterValue=my-unique-bucket

The domain must be verified in SES beforehand; that takes DNS records only you can set. Two steps the template cannot finish, and each is one command: activating the rule set (there is no CloudFormation resource for it) and minting an access key. The template deliberately creates none: a key in a stack output is readable by anyone who can read the stack, and stays that way.

aws ses set-active-receipt-rule-set --rule-set-name s3mail-info
aws iam create-access-key --user-name s3mail-info

IAM policy

{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::MY-BUCKET",
      "Condition": {"StringLike": {"s3:prefix": ["mail/*"]}} },
    { "Effect": "Allow", "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::MY-BUCKET/mail/*" },
    { "Effect": "Allow", "Action": "ses:SendRawEmail", "Resource": "*" },
    { "Effect": "Allow", "Action": ["sqs:ReceiveMessage", "sqs:DeleteMessage"],
      "Resource": "arn:aws:sqs:REGION:ACCOUNT:MY-QUEUE" },
    { "Effect": "Allow", "Action": ["kms:Decrypt", "kms:GenerateDataKey"],
      "Resource": "arn:aws:kms:REGION:ACCOUNT:key/YOUR-KEY" }
  ]
}

The KMS part goes away when neither the bucket nor the SES rule encrypts. The SQS part goes away when there is no doorbell; the sync then runs on a timer. sqs:GetQueueUrl is deliberately absent: s3mail builds the URL from the ARN it reads from the policy anyway.

Bucket, folder, sender address and queue are already in the policy, as exactly the value AWS later measures access against. If the identity may read its own policy (iam:ListUserPolicies, iam:GetUserPolicy on user/${aws:username}), s3mail fetches them from there instead of asking: all you enter is the access key and secret. Only inline policies are read. The region is what S3 itself names in its response header.

Optional, purely for the wizard's convenience: s3:ListAllMyBuckets (bucket picker; deliberately not in the policy above, because it shows every bucket in the account), ses:ListIdentities and ses:GetIdentityVerificationAttributes (sender picker), s3:GetLifecycleConfiguration and s3:PutLifecycleConfiguration (automatic trash emptying).

First start

./s3mail

On start, s3mail prints an address to the terminal that contains a token: s3mail running on 127.0.0.1.. The browser opens with it on its own. Without that token the server does not answer.

The first time, the setup wizard opens instead of the mailbox, in three steps: AWS access (pick a profile or enter access key ID + secret, plus the region), Mailbox (bucket, prefix from the SES rule, sender address for replies, optionally a signature and a name for the switcher), Check (briefly creates a test object and deletes it again; the result is a checklist, and what is missing is spelled out). Afterwards you can optionally set a lifecycle rule that empties the trash after 7/30/90 days.

“Save and start” writes ~/.config/s3mail/config.json (chmod 600) and loads the mailbox straight away. From then on ./s3mail is enough. Settings at the top right takes you back into the wizard at any time, also for a second mailbox.

Options