Help us shape the future of Go! Take the 2026 Go Developer Survey

postbox

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Aug 4, 2026 License: MIT Imports: 17 Imported by: 0

README

Postbox Go SDK

Official Go client for Postbox, mailbox infrastructure for developers. Provision real mailboxes over REST, send and receive mail, stream events, and verify webhooks. One client covers both the data plane and the management plane. Standard library only, no dependencies.

Install

go get github.com/postboxapp/postbox-go@latest

Requires Go 1.22+.

Quickstart

package main

import (
	"context"
	"log"

	postbox "github.com/postboxapp/postbox-go"
)

func main() {
	pb, err := postbox.NewWithKey("pb_live_...")
	if err != nil {
		log.Fatal(err)
	}

	res, err := pb.Messages.Send(context.Background(), &postbox.MessagesSendBody{
		From:     "support@acme.com",
		To:       []map[string]any{{"address": "jess@northwind.io"}},
		Subject:  "Welcome to Acme",
		BodyHtml: "<p>Glad you are here.</p>",
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Println(res.MessageId)
}

For a project-scoped key, custom base URL, timeout, or retries:

pb, err := postbox.New(postbox.Options{
	APIKey:     os.Getenv("PB_KEY"),
	ProjectID:  os.Getenv("PROJECT_ID"), // sets X-Project-Id on every request
	TimeoutMs:  30000,
	MaxRetries: 2,
})

What you get

  • One client, both planes: pb.Messages.Send(...) and pb.Domains.Create(...).

  • Typed errors: failures are a *postbox.Error with Status, Code, and RequestID; use postbox.IsRateLimit(err), IsNotFound, IsValidation, IsAuth.

  • Idempotent sends: an Idempotency-Key is attached to writes and reused across retries, so a retried send never duplicates.

  • Real-time events over SSE with automatic reconnect:

    pb.Stream(ctx, func(e postbox.Event) error {
	log.Println(e.Event)
	return nil
})

  • Webhook signature verification: postbox.VerifyWebhook(payload, signatureHeader, secret).

Retries, idempotency, event streaming, and webhook verification are built in and behave consistently across every Postbox SDK.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsAuth 

func IsAuth(err error) bool

IsAuth reports whether err is a 401/403 authentication or permission error.

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound reports whether err is a 404 not-found error.

func IsRateLimit 

func IsRateLimit(err error) bool

IsRateLimit reports whether err is a 429 rate-limit error.

func IsValidation 

func IsValidation(err error) bool

IsValidation reports whether err is a 400/422 validation error.

func VerifyWebhook 

func VerifyWebhook(payload, signatureHeader, secret string) bool

VerifyWebhook reports whether signatureHeader is a valid HMAC-SHA256 signature of payload under secret. The comparison is timing-safe. The header may be a bare hex digest, a "sha256=<hex>" value, or a structured "t=<ts>,v1=<hex>" value; every candidate signature it contains is checked.

Types

type Account 

type Account struct {
	Id            string `json:"id"`
	Name          string `json:"name"`
	Slug          string `json:"slug"`
	Plan          string `json:"plan"`
	Status        string `json:"status"`
	BillingActive bool   `json:"billingActive"`
	BillingEmail  string `json:"billingEmail"`
	Region        string `json:"region"`
	OnboardedAt   string `json:"onboardedAt"`
	CreatedAt     string `json:"createdAt"`
}

type AccountResource 

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

func (*AccountResource) Get 

func (r *AccountResource) Get(ctx context.Context) (*Account, error)

Get GET /account

func (*AccountResource) Update 

func (r *AccountResource) Update(ctx context.Context, body *AccountUpdateBody) (*Account, error)

Update PATCH /account

type AccountUpdateBody 

type AccountUpdateBody struct {
	Name         string `json:"name,omitempty"`
	BillingEmail string `json:"billingEmail,omitempty"`
}

type ApiKey 

type ApiKey struct {
	Id          string   `json:"id"`
	KeyPrefix   string   `json:"keyPrefix"`
	Label       string   `json:"label"`
	Permissions []string `json:"permissions"`
	LastUsedAt  string   `json:"lastUsedAt"`
	ExpiresAt   string   `json:"expiresAt"`
	Active      bool     `json:"active"`
}

type ApiKeysCreateBody 

type ApiKeysCreateBody struct {
	Label       string   `json:"label"`
	Permissions []string `json:"permissions,omitempty"`
	ExpiresIn   any      `json:"expiresIn,omitempty"`
}

type ApiKeysResource 

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

func (*ApiKeysResource) Create 

func (r *ApiKeysResource) Create(ctx context.Context, body *ApiKeysCreateBody) (*CreatedApiKey, error)

Create POST /api-keys

func (*ApiKeysResource) Delete 

func (r *ApiKeysResource) Delete(ctx context.Context, id string) (any, error)

Delete DELETE /api-keys/{id}

func (*ApiKeysResource) List 

func (r *ApiKeysResource) List(ctx context.Context) ([]ApiKey, error)

List GET /api-keys

type BounceRecord 

type BounceRecord struct {
	Id                string `json:"id"`
	TenantId          string `json:"tenantId"`
	ProjectId         string `json:"projectId"`
	ProviderMessageId string `json:"providerMessageId"`
	Address           string `json:"address"`
	BounceType        string `json:"bounceType"`
	BounceCode        string `json:"bounceCode"`
	OriginalFrom      string `json:"originalFrom"`
	OccurredAt        string `json:"occurredAt"`
	Suppressed        bool   `json:"suppressed"`
}

type BouncesPage 

type BouncesPage struct {
	Items      []BounceRecord `json:"items"`
	Total      float64        `json:"total"`
	Page       float64        `json:"page"`
	PageSize   float64        `json:"pageSize"`
	TotalPages float64        `json:"totalPages"`
}

type Client 

type Client struct {
	Account       *AccountResource
	ApiKeys       *ApiKeysResource
	Domains       *DomainsResource
	Folders       *FoldersResource
	InboundPolicy *InboundPolicyResource
	Logs          *LogsResource
	MailboxGroups *MailboxGroupsResource
	Mailboxes     *MailboxesResource
	Messages      *MessagesResource
	SenderRules   *SenderRulesResource
	Stats         *StatsResource
	Tokens        *TokensResource
	Webhooks      *WebhooksResource
	// contains filtered or unexported fields
}

Client is the unified Postbox client: one key, both planes.

func New 

func New(opts Options) (*Client, error)

New builds a client from options.

func NewWithKey 

func NewWithKey(apiKey string) (*Client, error)

NewWithKey builds a client from just an API key.

func (*Client) Stream 

func (cl *Client) Stream(ctx context.Context, handler func(Event) error) error

Stream opens the server-sent events stream and calls handler per event.

type CreatedApiKey 

type CreatedApiKey struct {
	Id          string   `json:"id"`
	ApiKey      string   `json:"apiKey"`
	KeyPrefix   string   `json:"keyPrefix"`
	Label       string   `json:"label"`
	Permissions []string `json:"permissions"`
	ExpiresAt   string   `json:"expiresAt"`
	Active      bool     `json:"active"`
}

type DeliverabilityDay 

type DeliverabilityDay struct {
	Id             string  `json:"id"`
	Date           string  `json:"date"`
	SentCount      float64 `json:"sentCount"`
	DeliveredCount float64 `json:"deliveredCount"`
	BouncedCount   float64 `json:"bouncedCount"`
	DeferredCount  float64 `json:"deferredCount"`
	ComplaintCount float64 `json:"complaintCount"`
	DeliveryRate   string  `json:"deliveryRate"`
	BounceRate     string  `json:"bounceRate"`
	ComplaintRate  string  `json:"complaintRate"`
}

type Domain 

type Domain struct {
	Id               string         `json:"id"`
	Domain           string         `json:"domain"`
	Status           string         `json:"status"`
	Region           string         `json:"region"`
	ReceivingEnabled bool           `json:"receivingEnabled"`
	Checks           map[string]any `json:"checks"`
	CreatedAt        string         `json:"createdAt"`
}

type DomainDetail 

type DomainDetail struct {
	Id               string            `json:"id"`
	Domain           string            `json:"domain"`
	Status           string            `json:"status"`
	Region           string            `json:"region"`
	ReceivingEnabled bool              `json:"receivingEnabled"`
	Checks           map[string]any    `json:"checks"`
	CreatedAt        string            `json:"createdAt"`
	Records          []DomainDnsRecord `json:"records"`
	Verification     map[string]any    `json:"verification"`
}

type DomainDnsRecord 

type DomainDnsRecord struct {
	Type     string  `json:"type"`
	Host     string  `json:"host"`
	Value    string  `json:"value"`
	Priority float64 `json:"priority"`
	Purpose  string  `json:"purpose"`
	Optional bool    `json:"optional"`
	Verified bool    `json:"verified"`
}

type DomainsCreateBody 

type DomainsCreateBody struct {
	Domain           string `json:"domain"`
	Region           string `json:"region,omitempty"`
	ReceivingEnabled bool   `json:"receivingEnabled,omitempty"`
}

type DomainsResource 

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

func (*DomainsResource) Create 

func (r *DomainsResource) Create(ctx context.Context, body *DomainsCreateBody) (*DomainDetail, error)

Create POST /domains

func (*DomainsResource) Delete 

func (r *DomainsResource) Delete(ctx context.Context, id string) (any, error)

Delete DELETE /domains/{id}

func (*DomainsResource) Get 

func (r *DomainsResource) Get(ctx context.Context, id string) (*DomainDetail, error)

Get GET /domains/{id}

func (*DomainsResource) List 

func (r *DomainsResource) List(ctx context.Context) ([]Domain, error)

List GET /domains

func (*DomainsResource) ListRecords 

func (r *DomainsResource) ListRecords(ctx context.Context, id string) ([]DomainDnsRecord, error)

ListRecords GET /domains/{id}/records

func (*DomainsResource) Verify 

func (r *DomainsResource) Verify(ctx context.Context, id string) (*DomainDetail, error)

Verify POST /domains/{id}/verify

type Error 

type Error struct {
	Status  int
	Code    string
	Message string
	// RequestID is populated from the X-Request-Id response header.
	RequestID string
	// RetryAfter is the Retry-After value in seconds, set only on 429s that
	// carried the header.
	RetryAfter int
}

Error is the single typed error the SDK returns for any non-2xx response. The (Status, Code) pair is stable across every Postbox SDK: a 409 is a conflict everywhere. RequestID is the string a customer quotes in a ticket.

func (*Error) Error 

func (e *Error) Error() string

type Event 

type Event struct {
	ID    string
	Event string
	Data  string
}

Event is a single server-sent event. Data is the raw data payload (data lines joined by newlines); decode it with encoding/json as needed.

type Folder 

type Folder struct {
	Id           string  `json:"id"`
	MailboxId    string  `json:"mailboxId"`
	Name         string  `json:"name"`
	SpecialUse   string  `json:"specialUse"`
	MessageCount float64 `json:"messageCount"`
	UnreadCount  float64 `json:"unreadCount"`
}

type FoldersDeleteQuery 

type FoldersDeleteQuery struct {
	Force string `json:"force,omitempty"`
}

type FoldersResource 

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

func (*FoldersResource) Delete 

func (r *FoldersResource) Delete(ctx context.Context, id string, query *FoldersDeleteQuery) (any, error)

Delete DELETE /folders/{id}

func (*FoldersResource) Update 

func (r *FoldersResource) Update(ctx context.Context, id string, body *FoldersUpdateBody) (*Folder, error)

Update PATCH /folders/{id}

type FoldersUpdateBody 

type FoldersUpdateBody struct {
	Name string `json:"name"`
}

type InboundPolicy 

type InboundPolicy struct {
	Id                string   `json:"id"`
	TenantId          string   `json:"tenantId"`
	ProjectId         string   `json:"projectId"`
	SpamThreshold     string   `json:"spamThreshold"`
	RejectNoSpf       bool     `json:"rejectNoSpf"`
	RejectNoDkim      bool     `json:"rejectNoDkim"`
	DmarcEnforce      bool     `json:"dmarcEnforce"`
	MaxMessageSize    float64  `json:"maxMessageSize"`
	BlockedExtensions []string `json:"blockedExtensions"`
	GreylistEnabled   bool     `json:"greylistEnabled"`
	ActionOnSpam      string   `json:"actionOnSpam"`
	CreatedAt         string   `json:"createdAt"`
	UpdatedAt         string   `json:"updatedAt"`
}

type InboundPolicyResource 

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

func (*InboundPolicyResource) Get 

func (r *InboundPolicyResource) Get(ctx context.Context) (*InboundPolicy, error)

Get GET /inbound-policy/inbound

func (*InboundPolicyResource) Update 

func (r *InboundPolicyResource) Update(ctx context.Context, body *InboundPolicyUpdateBody) (*InboundPolicy, error)

Update PATCH /inbound-policy/inbound

type InboundPolicyUpdateBody 

type InboundPolicyUpdateBody struct {
	SpamThreshold  float64 `json:"spamThreshold,omitempty"`
	ActionOnSpam   string  `json:"actionOnSpam,omitempty"`
	RejectNoSpf    bool    `json:"rejectNoSpf,omitempty"`
	RejectNoDkim   bool    `json:"rejectNoDkim,omitempty"`
	MaxMessageSize float64 `json:"maxMessageSize,omitempty"`
}

type LogsResource 

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

func (*LogsResource) Outbound 

func (r *LogsResource) Outbound(ctx context.Context) (*OutboundLogsPage, error)

Outbound GET /logs/outbound

type Mailbox 

type Mailbox struct {
	Id          string `json:"id"`
	Email       string `json:"email"`
	DisplayName string `json:"displayName"`
	Status      string `json:"status"`
	CreatedAt   string `json:"createdAt"`
}

type MailboxGroup 

type MailboxGroup struct {
	Id                 string  `json:"id"`
	TenantId           string  `json:"tenantId"`
	ProjectId          string  `json:"projectId"`
	Name               string  `json:"name"`
	HourlyLimit        float64 `json:"hourlyLimit"`
	DailyLimit         float64 `json:"dailyLimit"`
	BurstLimit         float64 `json:"burstLimit"`
	SpamScoreThreshold string  `json:"spamScoreThreshold"`
	ActionOnSpam       string  `json:"actionOnSpam"`
	RetentionDays      float64 `json:"retentionDays"`
	CreatedAt          string  `json:"createdAt"`
	UpdatedAt          string  `json:"updatedAt"`
}

type MailboxGroupsCreateBody 

type MailboxGroupsCreateBody struct {
	Name               string  `json:"name"`
	HourlyLimit        float64 `json:"hourlyLimit,omitempty"`
	DailyLimit         float64 `json:"dailyLimit,omitempty"`
	BurstLimit         float64 `json:"burstLimit,omitempty"`
	SpamScoreThreshold float64 `json:"spamScoreThreshold,omitempty"`
	ActionOnSpam       string  `json:"actionOnSpam,omitempty"`
	RetentionDays      float64 `json:"retentionDays,omitempty"`
}

type MailboxGroupsResource 

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

func (*MailboxGroupsResource) Create 

func (r *MailboxGroupsResource) Create(ctx context.Context, body *MailboxGroupsCreateBody) (*MailboxGroup, error)

Create POST /mailbox-groups

func (*MailboxGroupsResource) Delete 

func (r *MailboxGroupsResource) Delete(ctx context.Context, id string) (any, error)

Delete DELETE /mailbox-groups/{id}

func (*MailboxGroupsResource) Get 

func (r *MailboxGroupsResource) Get(ctx context.Context, id string) (*MailboxGroup, error)

Get GET /mailbox-groups/{id}

func (*MailboxGroupsResource) List 

func (r *MailboxGroupsResource) List(ctx context.Context) ([]MailboxGroup, error)

List GET /mailbox-groups

func (*MailboxGroupsResource) Update 

func (r *MailboxGroupsResource) Update(ctx context.Context, id string, body *MailboxGroupsUpdateBody) (*MailboxGroup, error)

Update PATCH /mailbox-groups/{id}

type MailboxGroupsUpdateBody 

type MailboxGroupsUpdateBody struct {
	Name               string  `json:"name,omitempty"`
	HourlyLimit        float64 `json:"hourlyLimit,omitempty"`
	DailyLimit         float64 `json:"dailyLimit,omitempty"`
	BurstLimit         float64 `json:"burstLimit,omitempty"`
	SpamScoreThreshold float64 `json:"spamScoreThreshold,omitempty"`
	ActionOnSpam       string  `json:"actionOnSpam,omitempty"`
	RetentionDays      float64 `json:"retentionDays,omitempty"`
}

type MailboxTokenRevocation 

type MailboxTokenRevocation struct {
	Revoked int64 `json:"revoked"`
}

type MailboxesCreateBody 

type MailboxesCreateBody struct {
	DomainId    string `json:"domainId"`
	LocalPart   string `json:"localPart"`
	DisplayName string `json:"displayName"`
	Quota       any    `json:"quota,omitempty"`
	GroupId     string `json:"groupId,omitempty"`
}

type MailboxesCreateFolderBody 

type MailboxesCreateFolderBody struct {
	Name string `json:"name"`
}

type MailboxesListMessagesQuery 

type MailboxesListMessagesQuery struct {
	Folder   string `json:"folder,omitempty"`
	Read     string `json:"read,omitempty"`
	Starred  string `json:"starred,omitempty"`
	Q        string `json:"q,omitempty"`
	Page     string `json:"page,omitempty"`
	PageSize string `json:"pageSize,omitempty"`
	Threaded string `json:"threaded,omitempty"`
}

type MailboxesListQuery 

type MailboxesListQuery struct {
	DomainId string `json:"domainId,omitempty"`
}

type MailboxesResource 

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

func (*MailboxesResource) Create 

func (r *MailboxesResource) Create(ctx context.Context, body *MailboxesCreateBody) (*Mailbox, error)

Create POST /mailboxes

func (*MailboxesResource) CreateFolder 

func (r *MailboxesResource) CreateFolder(ctx context.Context, id string, body *MailboxesCreateFolderBody) (*Folder, error)

CreateFolder POST /mailboxes/{id}/folders

func (*MailboxesResource) Delete 

func (r *MailboxesResource) Delete(ctx context.Context, id string) (any, error)

Delete DELETE /mailboxes/{id}

func (*MailboxesResource) Get 

func (r *MailboxesResource) Get(ctx context.Context, id string) (*Mailbox, error)

Get GET /mailboxes/{id}

func (*MailboxesResource) List 

func (r *MailboxesResource) List(ctx context.Context, query *MailboxesListQuery) ([]Mailbox, error)

List GET /mailboxes

func (*MailboxesResource) ListFolders 

func (r *MailboxesResource) ListFolders(ctx context.Context, id string) ([]Folder, error)

ListFolders GET /mailboxes/{id}/folders

func (*MailboxesResource) ListMessages 

func (r *MailboxesResource) ListMessages(ctx context.Context, id string, query *MailboxesListMessagesQuery) (*MessageList, error)

ListMessages GET /mailboxes/{id}/messages

func (*MailboxesResource) Tokens 

func (r *MailboxesResource) Tokens(ctx context.Context, mailboxId string) (*MailboxTokenRevocation, error)

Tokens DELETE /mailboxes/{mailboxId}/tokens

func (*MailboxesResource) Update 

func (r *MailboxesResource) Update(ctx context.Context, id string, body *MailboxesUpdateBody) (*Mailbox, error)

Update PATCH /mailboxes/{id}

type MailboxesUpdateBody 

type MailboxesUpdateBody struct {
	DisplayName string `json:"displayName,omitempty"`
	Quota       any    `json:"quota,omitempty"`
	Status      any    `json:"status,omitempty"`
	GroupId     string `json:"groupId,omitempty"`
}

type Message 

type Message struct {
	Id              string              `json:"id"`
	TenantId        string              `json:"tenantId"`
	ProjectId       string              `json:"projectId"`
	MailboxId       string              `json:"mailboxId"`
	FolderId        string              `json:"folderId"`
	MessageIdHeader string              `json:"messageIdHeader"`
	ThreadId        string              `json:"threadId"`
	FromAddress     string              `json:"fromAddress"`
	FromName        string              `json:"fromName"`
	ToAddresses     []map[string]any    `json:"toAddresses"`
	CcAddresses     []map[string]any    `json:"ccAddresses"`
	BccAddresses    []map[string]any    `json:"bccAddresses"`
	Subject         string              `json:"subject"`
	BodyText        string              `json:"bodyText"`
	BodyHtml        string              `json:"bodyHtml"`
	SizeBytes       float64             `json:"sizeBytes"`
	HasAttachments  bool                `json:"hasAttachments"`
	Read            bool                `json:"read"`
	Starred         bool                `json:"starred"`
	SpamScore       string              `json:"spamScore"`
	SentAt          string              `json:"sentAt"`
	ReceivedAt      string              `json:"receivedAt"`
	Attachments     []MessageAttachment `json:"attachments"`
}

type MessageAttachment 

type MessageAttachment struct {
	Id        string `json:"id"`
	MessageId string `json:"messageId"`
	Filename  string `json:"filename"`
	MimeType  string `json:"mimeType"`
	SizeBytes string `json:"sizeBytes"`
	ContentId string `json:"contentId"`
}

type MessageList 

type MessageList struct {
	Messages   []MessageSummary `json:"messages"`
	Threads    []MessageThread  `json:"threads"`
	Pagination map[string]any   `json:"pagination"`
}

type MessageSummary 

type MessageSummary struct {
	Id              string           `json:"id"`
	TenantId        string           `json:"tenantId"`
	ProjectId       string           `json:"projectId"`
	MailboxId       string           `json:"mailboxId"`
	FolderId        string           `json:"folderId"`
	MessageIdHeader string           `json:"messageIdHeader"`
	ThreadId        string           `json:"threadId"`
	FromAddress     string           `json:"fromAddress"`
	FromName        string           `json:"fromName"`
	ToAddresses     []map[string]any `json:"toAddresses"`
	CcAddresses     []map[string]any `json:"ccAddresses"`
	BccAddresses    []map[string]any `json:"bccAddresses"`
	Subject         string           `json:"subject"`
	BodyText        string           `json:"bodyText"`
	BodyHtml        string           `json:"bodyHtml"`
	SizeBytes       float64          `json:"sizeBytes"`
	HasAttachments  bool             `json:"hasAttachments"`
	Read            bool             `json:"read"`
	Starred         bool             `json:"starred"`
	SpamScore       string           `json:"spamScore"`
	SentAt          string           `json:"sentAt"`
	ReceivedAt      string           `json:"receivedAt"`
}

type MessageThread 

type MessageThread struct {
	Id            string           `json:"id"`
	Subject       string           `json:"subject"`
	From          string           `json:"from"`
	Preview       string           `json:"preview"`
	Ts            string           `json:"ts"`
	Unread        bool             `json:"unread"`
	Starred       bool             `json:"starred"`
	MessagesCount float64          `json:"messagesCount"`
	Messages      []MessageSummary `json:"messages"`
}

type MessagesGetStatusByKeyQuery 

type MessagesGetStatusByKeyQuery struct {
	IdempotencyKey string `json:"idempotencyKey"`
}

type MessagesResource 

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

func (*MessagesResource) Delete 

func (r *MessagesResource) Delete(ctx context.Context, id string) (any, error)

Delete DELETE /messages/{id}

func (*MessagesResource) Get 

func (r *MessagesResource) Get(ctx context.Context, id string) (*Message, error)

Get GET /messages/{id}

func (*MessagesResource) GetStatus 

func (r *MessagesResource) GetStatus(ctx context.Context, id string) (*OutboundStatus, error)

GetStatus GET /messages/{id}/status

func (*MessagesResource) GetStatusByKey 

func (r *MessagesResource) GetStatusByKey(ctx context.Context, query *MessagesGetStatusByKeyQuery) (*OutboundStatus, error)

GetStatusByKey GET /messages/status

func (*MessagesResource) Send 

func (r *MessagesResource) Send(ctx context.Context, body *MessagesSendBody) (*SendResult, error)

Send POST /messages/send

type MessagesSendBody 

type MessagesSendBody struct {
	From        string           `json:"from"`
	To          []map[string]any `json:"to"`
	Cc          []map[string]any `json:"cc,omitempty"`
	Bcc         []map[string]any `json:"bcc,omitempty"`
	Subject     string           `json:"subject"`
	BodyText    string           `json:"bodyText,omitempty"`
	BodyHtml    string           `json:"bodyHtml,omitempty"`
	Attachments []map[string]any `json:"attachments,omitempty"`
	ThreadId    string           `json:"threadId,omitempty"`
	ReplyTo     string           `json:"replyTo,omitempty"`
}

type Options 

type Options struct {
	// APIKey is the bearer credential (pb_live_... or pb_test_...). Required.
	APIKey string
	// BaseURL is the API root. Defaults to https://api.postboxapp.cloud/v1.
	BaseURL string
	// ProjectID, when set, is sent as the X-Project-Id header on every request.
	ProjectID string
	// TimeoutMs is the per-attempt timeout in milliseconds. Defaults to 30000.
	TimeoutMs int
	// MaxRetries is the number of EXTRA attempts on retryable failures.
	// Defaults to 2.
	MaxRetries int
	// DefaultHeaders are merged into every request.
	DefaultHeaders map[string]string
	// HTTPClient lets callers inject a custom *http.Client (proxy, transport).
	// When nil a default client is used.
	HTTPClient *http.Client
}

Options configures a Postbox client. Only APIKey is required; every other field has a sensible default applied in newClient.

type OutboundLog 

type OutboundLog struct {
	Id                string  `json:"id"`
	TenantId          string  `json:"tenantId"`
	ProjectId         string  `json:"projectId"`
	ProviderMessageId string  `json:"providerMessageId"`
	MessageId         string  `json:"messageId"`
	FromAddress       string  `json:"fromAddress"`
	ToAddress         string  `json:"toAddress"`
	Status            string  `json:"status"`
	Attempts          float64 `json:"attempts"`
	LastAttemptAt     string  `json:"lastAttemptAt"`
	NextRetryAt       string  `json:"nextRetryAt"`
	SmtpResponse      string  `json:"smtpResponse"`
	BounceType        string  `json:"bounceType"`
	BounceCode        string  `json:"bounceCode"`
	QueuedAt          string  `json:"queuedAt"`
	SentAt            string  `json:"sentAt"`
	DeliveredAt       string  `json:"deliveredAt"`
}

type OutboundLogsPage 

type OutboundLogsPage struct {
	Items      []OutboundLog `json:"items"`
	Total      float64       `json:"total"`
	Page       float64       `json:"page"`
	PageSize   float64       `json:"pageSize"`
	TotalPages float64       `json:"totalPages"`
}

type OutboundStatus 

type OutboundStatus struct {
	MessageId         string  `json:"messageId"`
	Status            string  `json:"status"`
	Terminal          bool    `json:"terminal"`
	ProviderMessageId string  `json:"providerMessageId"`
	Attempts          float64 `json:"attempts"`
	BounceType        string  `json:"bounceType"`
	BounceCode        string  `json:"bounceCode"`
	QueuedAt          string  `json:"queuedAt"`
	SentAt            string  `json:"sentAt"`
	DeliveredAt       string  `json:"deliveredAt"`
}

type SendResult 

type SendResult struct {
	MessageId string `json:"messageId"`
	ThreadId  string `json:"threadId"`
}

type SenderRule 

type SenderRule struct {
	Id        string `json:"id"`
	TenantId  string `json:"tenantId"`
	ProjectId string `json:"projectId"`
	RuleType  string `json:"ruleType"`
	MatchType string `json:"matchType"`
	Value     string `json:"value"`
	Action    string `json:"action"`
	Reason    string `json:"reason"`
	CreatedAt string `json:"createdAt"`
}

type SenderRulesCreateBody 

type SenderRulesCreateBody struct {
	RuleType  string `json:"ruleType"`
	MatchType string `json:"matchType"`
	Value     string `json:"value"`
	Action    string `json:"action"`
	Reason    string `json:"reason,omitempty"`
}

type SenderRulesListQuery 

type SenderRulesListQuery struct {
	Type string `json:"type,omitempty"`
}

type SenderRulesResource 

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

func (*SenderRulesResource) Create 

func (r *SenderRulesResource) Create(ctx context.Context, body *SenderRulesCreateBody) (*SenderRule, error)

Create POST /sender-rules/rules

func (*SenderRulesResource) Delete 

func (r *SenderRulesResource) Delete(ctx context.Context, id string) (any, error)

Delete DELETE /sender-rules/rules/{id}

func (*SenderRulesResource) List 

func (r *SenderRulesResource) List(ctx context.Context, query *SenderRulesListQuery) ([]SenderRule, error)

List GET /sender-rules/rules

type StatsResource 

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

func (*StatsResource) Bounces 

func (r *StatsResource) Bounces(ctx context.Context) (*BouncesPage, error)

Bounces GET /stats/bounces

func (*StatsResource) Deliverability 

func (r *StatsResource) Deliverability(ctx context.Context) ([]DeliverabilityDay, error)

Deliverability GET /stats/deliverability

func (*StatsResource) Usage 

func (r *StatsResource) Usage(ctx context.Context) (*Usage, error)

Usage GET /stats/usage

type Token 

type Token struct {
	Id        string `json:"id"`
	Token     string `json:"token"`
	ExpiresAt string `json:"expiresAt"`
}

type TokenRevocation 

type TokenRevocation struct {
	Id        string `json:"id"`
	RevokedAt string `json:"revokedAt"`
}

type TokensCreateBody 

type TokensCreateBody struct {
	MailboxId   string   `json:"mailboxId"`
	Permissions []string `json:"permissions"`
	ExpiresIn   any      `json:"expiresIn,omitempty"`
}

type TokensResource 

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

func (*TokensResource) Create 

func (r *TokensResource) Create(ctx context.Context, body *TokensCreateBody) (*Token, error)

Create POST /tokens

func (*TokensResource) Revoke 

func (r *TokensResource) Revoke(ctx context.Context, id string) (*TokenRevocation, error)

Revoke POST /tokens/{id}/revoke

type Usage 

type Usage struct {
	TotalMailboxes        float64        `json:"totalMailboxes"`
	TotalStorageUsedBytes string         `json:"totalStorageUsedBytes"`
	TotalMessagesCount    float64        `json:"totalMessagesCount"`
	Plan                  map[string]any `json:"plan"`
	Limits                map[string]any `json:"limits"`
	Usage                 map[string]any `json:"usage"`
}

type Webhook 

type Webhook struct {
	Id     string   `json:"id"`
	Url    string   `json:"url"`
	Events []string `json:"events"`
	Active bool     `json:"active"`
}

type WebhookDelivery 

type WebhookDelivery struct {
	Id          string         `json:"id"`
	EndpointId  string         `json:"endpointId"`
	EventType   string         `json:"eventType"`
	Payload     map[string]any `json:"payload"`
	Status      string         `json:"status"`
	HttpStatus  float64        `json:"httpStatus"`
	Attempts    float64        `json:"attempts"`
	DeliveredAt string         `json:"deliveredAt"`
	CreatedAt   string         `json:"createdAt"`
}

type WebhooksCreateBody 

type WebhooksCreateBody struct {
	Url    string   `json:"url"`
	Secret string   `json:"secret"`
	Events []string `json:"events,omitempty"`
	Active bool     `json:"active,omitempty"`
}

type WebhooksResource 

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

func (*WebhooksResource) Create 

func (r *WebhooksResource) Create(ctx context.Context, body *WebhooksCreateBody) (*Webhook, error)

Create POST /webhooks

func (*WebhooksResource) Delete 

func (r *WebhooksResource) Delete(ctx context.Context, id string) (any, error)

Delete DELETE /webhooks/{id}

func (*WebhooksResource) List 

func (r *WebhooksResource) List(ctx context.Context) ([]Webhook, error)

List GET /webhooks

func (*WebhooksResource) ListDeliveries 

func (r *WebhooksResource) ListDeliveries(ctx context.Context, id string) ([]WebhookDelivery, error)

ListDeliveries GET /webhooks/{id}/deliveries

func (*WebhooksResource) Update 

func (r *WebhooksResource) Update(ctx context.Context, id string, body *WebhooksUpdateBody) (*Webhook, error)

Update PATCH /webhooks/{id}

type WebhooksUpdateBody 

type WebhooksUpdateBody struct {
	Url    string   `json:"url,omitempty"`
	Secret string   `json:"secret,omitempty"`
	Events []string `json:"events,omitempty"`
	Active bool     `json:"active,omitempty"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.