README
¶
togo-framework/mail-inbound
Inbound email parsing & routing for togo — turn emails into application actions.
Install
togo install togo-framework/mail-inbound
The togo answer to Laravel Mailbox / Rails Action Mailbox. Parse raw RFC-822 messages and provider webhooks (SendGrid Inbound Parse, Mailgun routes) into a normalized InboundMail, then route each message to a handler by recipient pattern or subject regex.
Usage
mb, _ := mailinbound.FromKernel(k)
// Route support@ → open a ticket
mb.Route(mailinbound.ToPrefix("support@"), func(ctx context.Context, m mailinbound.InboundMail) error {
return tickets.Open(m.From, m.Subject, m.Text)
})
// Route replies by plus-address token: reply+{token}@myapp.com
mb.Route(mailinbound.ToContains("reply+"), func(ctx context.Context, m mailinbound.InboundMail) error {
if token, ok := mailinbound.PlusToken(m); ok {
return threads.Append(token, m.Text)
}
return nil
})
// Match by subject
mb.Route(mailinbound.SubjectMatch(`(?i)invoice`), billingHandler)
// Anything unmatched
mb.CatchAll(func(ctx context.Context, m mailinbound.InboundMail) error { return inbox.Store(m) })
InboundMail carries From, To, Cc, Subject, Text, HTML, MessageID, Headers, and decoded Attachments.
Webhooks
Point your provider's inbound parse at these endpoints (mounted automatically):
| Method | Path | Provider |
|---|---|---|
POST |
/api/mail-inbound/sendgrid |
SendGrid Inbound Parse (multipart form) |
POST |
/api/mail-inbound/mailgun |
Mailgun routes (form fields) |
POST |
/api/mail-inbound/raw |
raw RFC-822 message |
GET |
/api/mail-inbound/received |
recent inbound log |
You can also parse directly: mailinbound.ParseRFC822(raw), FromSendGrid(req), FromMailgun(req).
Configuration
No required env. Set your DNS MX / provider inbound-parse to forward mail to the webhook URL, then register routes in your app. A bounded in-memory log keeps the most recent messages.
Documentation
¶
Overview ¶
Package mailinbound parses and routes inbound email for togo (Laravel Mailbox / Rails Action Mailbox). It parses raw RFC-822 messages and provider webhooks (SendGrid Inbound Parse, Mailgun routes) into a normalized InboundMail, then dispatches each message to the first matching handler — matched by recipient pattern or subject regex.
mb, _ := mailinbound.FromKernel(k)
mb.Route(mailinbound.ToPrefix("support@"), func(ctx context.Context, m mailinbound.InboundMail) error {
return openTicket(m)
})
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func PlusToken ¶
func PlusToken(m InboundMail) (string, bool)
PlusToken extracts the "+token" from a plus-addressed recipient (e.g. "reply+abc123@example.com" → "abc123", ok). Checks every recipient.
Types ¶
type Attachment ¶
type Attachment struct {
Filename string `json:"filename"`
ContentType string `json:"content_type"`
Data []byte `json:"-"`
Size int `json:"size"`
}
Attachment is a decoded email attachment.
type Handler ¶
type Handler func(ctx context.Context, m InboundMail) error
Handler processes an inbound message.
type InboundMail ¶
type InboundMail struct {
From string `json:"from"`
To []string `json:"to"`
Cc []string `json:"cc,omitempty"`
Subject string `json:"subject"`
Text string `json:"text,omitempty"`
HTML string `json:"html,omitempty"`
MessageID string `json:"message_id,omitempty"`
Headers map[string]string `json:"headers,omitempty"`
Attachments []Attachment `json:"attachments,omitempty"`
ReceivedAt time.Time `json:"received_at"`
}
InboundMail is a normalized inbound message.
func FromMailgun ¶
func FromMailgun(r *http.Request) (InboundMail, error)
FromMailgun normalizes a Mailgun route (form fields) request.
func FromSendGrid ¶
func FromSendGrid(r *http.Request) (InboundMail, error)
FromSendGrid normalizes a SendGrid Inbound Parse (multipart/form-data) request.
func ParseRFC822 ¶
func ParseRFC822(raw []byte) (InboundMail, error)
ParseRFC822 parses a raw RFC-822 message into an InboundMail (handles multipart bodies + attachments).
type Matcher ¶
type Matcher func(m InboundMail) bool
Matcher decides whether a handler should receive a message.
func SubjectMatch ¶
SubjectMatch matches when the subject matches the regular expression.
func ToContains ¶
ToContains matches when any recipient contains the substring.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the mail-inbound runtime stored on the kernel.
func FromKernel ¶
FromKernel returns the mail-inbound Service.
func (*Service) Dispatch ¶
func (s *Service) Dispatch(ctx context.Context, m InboundMail) error
Dispatch routes a message to the first matching handler (or the catch-all).
func (*Service) Received ¶
func (s *Service) Received() []InboundMail
Received returns the recent inbound log (newest last).
Source Files