Building on it
Email and Engage
Tillstack sends the email an account needs, and nothing else: it is transactional, not marketing. Marketing and journeys belong in Engage (see the end).
What is sent#
| When | Notes | |
|---|---|---|
| Invitation | A person is added with "email them an invitation" | A link (valid 7 days, once) to choose their own password. No password is ever emailed. |
| Password reset | "Forgot your password?" | A link valid for one hour, once. The reply to "forgot password" is identical whether or not the address has an account, and three requests an hour are the most that send. |
| End-of-day summary | A business turns it on (My business, Profile) | About 9 pm Nigerian time, to the owners: sales, best sellers, and anything that needs a look. At most once a day per business. |
| Test message | Platform staff, System page | To prove the server can send. |
Every message is multipart (HTML and plain text) and the business is the brand: its name, logo and colour lead, and Tillstack is a small credit in the footer (unless the business turned that off). A brand colour is only ever accepted as a hex value and links and images only as http(s), so nothing typed into a settings field can inject markup.
Setting it up#
Any SMTP server works: a hosted provider, a self-hosted relay, or MailHog locally. Set these on the API (environment variables, __ for nesting):
| Setting | Meaning |
|---|---|
Email__Host |
SMTP host. Empty turns sending off (it logs instead; invitations then fall back to a temporary password) |
Email__Port |
Usually 587 (STARTTLS) or 465 (implicit TLS) |
Email__UseSsl |
true for implicit TLS on 465 |
Email__Username, Email__Password |
Credentials, if the server needs them |
Email__FromAddress, Email__FromName |
The sender, for example no-reply@yourdomain.ng |
Email__SupportAddress |
Shown to people who need help |
Email__FooterAddress |
A postal address for the footer (spam filters look for one) |
App__ConsoleBaseUrl |
Where links in emails point (your console URL) |
App__SiteBaseUrl |
Used for the Privacy and Terms links |
DailySummary__Enabled, DailySummary__HourWat, DailySummary__CheckMinutes |
The summary sweep (default on, 21, 10) |
Locally: docker run -p 1025:1025 -p 8025:8025 mailhog/mailhog, then Email__Host=localhost, Email__Port=1025, and read mail at http://localhost:8025.
Check it works#
Back office, System: shows what is configured (the password is never shown, only whether one is set) and sends a test message, reporting the server's own answer. Or call
GET /v1/admin/email and POST /v1/admin/email/test {"to":"you@example.com"} as platform staff.
"Accepted" is not "delivered". The mail server taking a message says nothing about whether the recipient's provider accepts it. If mail is accepted but never arrives, it is almost always DNS for the sending
domain: publish SPF including your mail provider, DKIM (the key your provider gives you; never a wildcard *._domainkey record with an empty p=, which revokes DKIM for every selector), and a DMARC
policy. Start DMARC at p=none and tighten once mail flows. With strict alignment, DKIM must carry the message because SPF alone will not align on a provider's return path.
Engage: campaigns, journeys, consent#
Engage is the sibling product for messaging people over time: campaigns, journeys, segments, consent and unsubscribes. Tillstack deliberately does not duplicate it. Instead, feed Engage from the events Tillstack already emits.
- In Engage, create an inbound webhook source (Data in, Webhooks). It gives you an address like
/in/{prefix}/{token}and lets you declare which path in the body is the person, the event name, the time and an id. - In Tillstack, add a webhook endpoint for the organisation (
POST /v1/organizations/{id}/webhooks) pointing at that address, subscribed to the events you care about (sale.created,stock.low, ...). - Map the fields: our payload is
{ id, type, createdAt, livemode, merchantId, data }. Useidas Engage's id (so a retry is stored once),typeas the event,createdAtas the time, and the person from whichever field identifies them indata.
Or call Engage's Segment-compatible or /v1/track API from your own code when something happens. Engage keeps consent and unsubscribe state; Tillstack sends only the account mail above. This setup has not yet been exercised against
a live Engage instance, so treat the field mapping as a starting point.