Documentation
¶
Overview ¶
Package mail provides an HTTP client for the ping_api /mail/* endpoints.
The CLI's `nself mail` command wraps this client. ping_api in turn proxies to the mux + Postmark plugins to deliver transactional and broadcast email through the nSelf stack.
Authentication uses a bearer license token (NSELF_LICENSE_KEY or the configured license keys via internal/license.CollectLicenseKeys). The Postmark plugin is part of the nClaw / ɳSelf+ paid bundles, so the server will reject calls when no valid license is presented.
All methods are context-aware and return typed responses.
Index ¶
- Constants
- Variables
- type BroadcastRequest
- type BroadcastResponse
- type Client
- func (c *Client) Broadcast(ctx context.Context, req BroadcastRequest) (*BroadcastResponse, error)
- func (c *Client) ListTemplates(ctx context.Context) ([]Template, error)
- func (c *Client) Send(ctx context.Context, req SendRequest) (*SendResponse, error)
- func (c *Client) Status(ctx context.Context, messageID string) (*StatusResponse, error)
- func (c *Client) VerifyDKIM(ctx context.Context, domain string) (*DKIMVerifyResponse, error)
- type DKIMVerifyResponse
- type ListTemplatesResponse
- type SendRequest
- type SendResponse
- type StatusResponse
- type Template
Constants ¶
const (
// DefaultPingURL is the production mail proxy.
DefaultPingURL = "https://ping.nself.org"
)
Variables ¶
var ( // Indicates a missing, expired, or revoked license key. ErrUnauthorized = errors.New("unauthorized: nself mail requires nSelf+ or nClaw bundle (Postmark plugin)") // ErrUnreachable is returned when the network round-trip fails. ErrUnreachable = errors.New("ping.nself.org unreachable, check connectivity") // ErrServer is returned for any 5xx response. ErrServer = errors.New("ping_api server error") )
Errors returned by the client. Callers can compare with errors.Is.
Functions ¶
This section is empty.
Types ¶
type BroadcastRequest ¶
type BroadcastRequest struct {
ListID string `json:"list_id"`
TemplateID string `json:"template_id"`
}
BroadcastRequest is the JSON body for POST /mail/broadcast.
type BroadcastResponse ¶
type BroadcastResponse struct {
BatchID string `json:"batch_id"`
Recipients int `json:"recipients"`
Queued bool `json:"queued"`
}
BroadcastResponse is the response body for POST /mail/broadcast.
type Client ¶
Client is a thin wrapper over http.Client with auth + base URL pinned.
func New ¶
New constructs a Client. baseURL falls back to DefaultPingURL when empty. licenseKey may be empty; in that case auth-required endpoints will fail with ErrUnauthorized.
func (*Client) Broadcast ¶
func (c *Client) Broadcast(ctx context.Context, req BroadcastRequest) (*BroadcastResponse, error)
Broadcast queues a list-based broadcast email job.
func (*Client) ListTemplates ¶
ListTemplates fetches all Postmark templates registered with the nSelf stack.
func (*Client) Send ¶
func (c *Client) Send(ctx context.Context, req SendRequest) (*SendResponse, error)
Send delivers a single transactional email through mux + Postmark.
func (*Client) VerifyDKIM ¶
VerifyDKIM checks for a valid DKIM record on the supplied domain.
type DKIMVerifyResponse ¶
type DKIMVerifyResponse struct {
Domain string `json:"domain"`
Valid bool `json:"valid"`
Selector string `json:"selector,omitempty"`
Record string `json:"record,omitempty"`
Detail string `json:"detail,omitempty"`
}
DKIMVerifyResponse is the response body for GET /mail/dkim/verify.
type ListTemplatesResponse ¶
type ListTemplatesResponse struct {
Templates []Template `json:"templates"`
}
ListTemplatesResponse is the response body for GET /mail/templates.
type SendRequest ¶
type SendRequest struct {
To string `json:"to"`
Subject string `json:"subject"`
Body string `json:"body"`
BodyType string `json:"body_type,omitempty"` // "text" (default) or "html"
}
SendRequest is the JSON body for POST /mail/send.
type SendResponse ¶
type SendResponse struct {
MessageID string `json:"message_id"`
Accepted bool `json:"accepted"`
To string `json:"to"`
}
SendResponse is the response body for POST /mail/send.
type StatusResponse ¶
type StatusResponse struct {
MessageID string `json:"message_id"`
Status string `json:"status"` // delivered, bounced, spam_complaint, queued, sent
To string `json:"to,omitempty"`
DeliveredAt string `json:"delivered_at,omitempty"`
BouncedAt string `json:"bounced_at,omitempty"`
BounceType string `json:"bounce_type,omitempty"`
Detail string `json:"detail,omitempty"`
}
StatusResponse is the response body for GET /mail/status.
type Template ¶
type Template struct {
ID string `json:"id"`
Name string `json:"name"`
Subject string `json:"subject,omitempty"`
Updated string `json:"updated,omitempty"`
Provider string `json:"provider,omitempty"` // typically "postmark"
}
Template describes a Postmark template registered with nSelf.
Source Files