mail

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 New(baseURL, licenseKey string) *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 (
	// ErrUnauthorized is returned when ping_api responds 401/403.
	// 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.

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

type Client struct {
	BaseURL    string
	LicenseKey string
	HTTP       *http.Client
}

Client is a thin wrapper over http.Client with auth + base URL pinned.

func New

func New(baseURL, licenseKey string) *Client

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

func (c *Client) ListTemplates(ctx context.Context) ([]Template, error)

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) Status

func (c *Client) Status(ctx context.Context, messageID string) (*StatusResponse, error)

Status queries the delivery status for a previously sent message.

func (*Client) VerifyDKIM

func (c *Client) VerifyDKIM(ctx context.Context, domain string) (*DKIMVerifyResponse, error)

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.