postal

package
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 30, 2026 License: AGPL-3.0 Imports: 26 Imported by: 0

Documentation

Overview

Package postal is the adapter for a self-hosted Postal server (postalserver.io). Webhooks are configured in Postal's web interface and signed with the server's RSA key (X-Postal-Signature-256, RS256 over the body), whose public half Postal publishes at /.well-known/jwks.json.

Postal has no API for domains, suppression lists or webhook management: ReputeCast enforces the shared suppression list before handing mail to Postal, and DNS records are set up by hand.

Index

Constants

View Source
const Adapter = "postal"

Adapter is the registry key.

View Source
const TagPrefix = "rc:"

TagPrefix marks the X-Postal-Tag that carries the ReputeCast message id.

Variables

This section is empty.

Functions

func Descriptor

func Descriptor() providers.Descriptor

Descriptor describes the adapter for the catalog.

func FetchJWKS

func FetchJWKS(ctx context.Context, hc *http.Client, server string) (map[string]*rsa.PublicKey, error)

FetchJWKS downloads a Postal server's webhook signing keys.

func New

New builds the adapter.

func ParseJWKS

func ParseJWKS(raw []byte) (map[string]*rsa.PublicKey, error)

ParseJWKS parses RSA keys from a JWK set.

func ParsePublicKey

func ParsePublicKey(s string) (*rsa.PublicKey, error)

ParsePublicKey reads a PEM ("BEGIN PUBLIC KEY" or "BEGIN RSA PUBLIC KEY") or base64 DER RSA public key.

Types

type Credentials

type Credentials struct {
	APIKey string `json:"api_key"`
}

Credentials are write-only.

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

Provider talks to one Postal mail server.

func (*Provider) Adapter

func (p *Provider) Adapter() string

Adapter implements providers.Provider.

func (*Provider) Backfill

func (p *Provider) Backfill(ctx context.Context, ids []string) ([]providers.Event, error)

Backfill implements providers.EventBackfiller with /api/v1/messages/deliveries: the latest delivery of each message.

func (*Provider) Capabilities

func (p *Provider) Capabilities() providers.Capabilities

Capabilities implements providers.Provider.

func (*Provider) ParseWebhook

func (p *Provider) ParseWebhook(ctx context.Context, r *http.Request, body []byte) ([]providers.Event, error)

ParseWebhook implements providers.Provider.

func (*Provider) Send

func (p *Provider) Send(ctx context.Context, msgs []providers.Message) ([]providers.SendResult, error)

Send implements providers.Provider through POST /api/v1/send/raw, one message per call (Postal has no batch endpoint).

func (*Provider) SendWithExtras

func (p *Provider) SendWithExtras(ctx context.Context, msgs []providers.Message, extras []providers.MessageExtras) ([]providers.SendResult, error)

SendWithExtras implements providers.ExtrasSender: copies and attachments go in the raw message, every recipient in rcpt_to.

func (*Provider) Verify

func (p *Provider) Verify(ctx context.Context) (providers.Quota, error)

Verify implements providers.Verifier: looking up message 0 answers MessageNotFound with a valid key and InvalidServerAPIKey otherwise, without side effects.

func (*Provider) VerifyWebhook

func (p *Provider) VerifyWebhook(ctx context.Context, r *http.Request, body []byte) error

VerifyWebhook checks X-Postal-Signature-256 (or the legacy SHA-1 signature) against the server's signing keys.

type Settings

type Settings struct {
	ServerURL string `json:"server_url"`
	// SigningJWKS is Postal's webhook signing key set, fetched from
	// /.well-known/jwks.json when the provider is connected.
	SigningJWKS json.RawMessage `json:"signing_jwks,omitempty"`
	// SigningKey is a PEM or base64 DER public key for Postal versions that
	// show the key instead of publishing a JWKS.
	SigningKey string `json:"signing_key,omitempty"`
	Version    string `json:"version,omitempty"`
}

Settings are the non-secret connection settings.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL