📬 Mailroom

Task processor and web service for RapidPro and TextIt.

Deploying

It compiles to a binary and can find bundles for each platform in the releases directory.

Configuration

The service uses a tiered configuration system, each option takes precendence over the ones above it:

1. The configuration file
2. Environment variables starting with MAILROOM_
3. Command line parameters

We recommend running it with no changes to the configuration and no parameters, using only environment variables to configure it. You can use % mailroom --help to see a list of the environment variables and parameters and for more details on each option.

• MAILROOM_PUBLIC_ADDRESS: address to bind our public web server to (serves /mr/* routes)
• MAILROOM_PUBLIC_PORT: port to bind our public web server to
• MAILROOM_INTERNAL_ADDRESS: address to bind our internal web server to (serves /mi/* routes)
• MAILROOM_INTERNAL_PORT: port to bind our internal web server to
• MAILROOM_DOMAIN: domain that mailroom is listening on
• MAILROOM_COURIER_ENDPOINT: base URL used for internal calls to courier, e.g. http://localhost:8080
• MAILROOM_AUTH_TOKEN: authentication token clients will need to for web requests (should match setting in RapidPro)
• MAILROOM_ATTACHMENT_DOMAIN: domain that will be used for relative attachments in flows
• MAILROOM_DB: URL describing how to connect to the RapidPro database
• MAILROOM_READONLY_DB: URL for an additional database connection for read-only operations (optional)
• MAILROOM_VALKEY: URL describing how to connect to Valkey
• MAILROOM_SMTP_SERVER: SMTP configuration for sending emails (e.g. smtp://user%40password@server:port/?from=foo%40gmail.com)
• MAILROOM_ANDROID_FCM_SERVICE_ACCOUNT_FILE: FCM Service Account Credentials JSON File path used to notify Android relayers to sync
• MAILROOM_ELASTIC_USERNAME: ElasticSearch username for Basic Auth
• MAILROOM_ELASTIC_PASSWORD: ElasticSearch password for Basic Auth
• MAILROOM_COURIER_AUTH_TOKEN: authentication token used for requests to Courier

AWS services:

• MAILROOM_S3_ATTACHMENTS_BUCKET: name of your S3 bucket (e.g. mailroom-attachments)

The AWS region and credentials are resolved via the standard AWS SDK default chain — the AWS_REGION (or AWS_DEFAULT_REGION) environment variable, the instance/task IAM role, AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY environment variables, the shared config/credentials files, etc. When running on AWS the task/instance role is the recommended option for credentials.

Logging and error reporting:

• MAILROOM_DEPLOYMENT_ID: used for metrics reporting
• MAILROOM_SENTRY_DSN: DSN to use when logging errors to Sentry
• MAILROOM_LOG_LEVEL: logging level to use