mailstack

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jun 21, 2026 License: MIT Imports: 13 Imported by: 0

README

MailStack Go SDK

The official Go SDK for MailStack — email that lands. Send transactional email, manage sending domains and templates, stream delivery events, and verify webhooks.

go get github.com/VooStack/mailstack-go

Requires Go 1.22+.

Quickstart

package main

import (
	"context"
	"fmt"
	"log"

	mailstack "github.com/VooStack/mailstack-go"
)

func main() {
	client := mailstack.New("ms_live_...")

	resp, err := client.Emails.Send(context.Background(), mailstack.SendEmailRequest{
		From:    "hello@yourdomain.com",
		To:      "user@example.com",
		Subject: "Welcome to MailStack",
		HTML:    "<h1>Hi there 👋</h1>",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("queued:", resp.ID, resp.Status)
}

Authentication

Every request sends your API key as a Bearer token. The send API (client.Emails) is authorized with the API key alone.

The dashboard-scoped resources — Domains, APIKeys, Templates, Messages, Webhooks — are authorized with a user JWT and require your organization id, sent as the X-MailStack-Org header. Provide it with WithOrgID:

client := mailstack.New("<jwt>", mailstack.WithOrgID("org_..."))

Other options: WithBaseURL(url) (defaults to https://api.mailstack.voostack.com) and WithHTTPClient(*http.Client) for custom timeouts/transports.

Sending email

to, cc, and bcc are comma-separated address lists. Build them from a slice with mailstack.JoinAddresses:

client.Emails.Send(ctx, mailstack.SendEmailRequest{
	From:      "hello@yourdomain.com",
	To:        mailstack.JoinAddresses("a@example.com", "b@example.com"),
	Subject:   "Hello",
	Text:      "Plain-text body",
	Tags:      "welcome,onboarding",
	Variables: map[string]any{"name": "Sam"},
})

Batch (up to 100 fully-specified emails) and bulk (one base message + per-recipient overrides):

client.Emails.SendBatch(ctx, []mailstack.SendEmailRequest{ /* ... */ })

client.Emails.Bulk(ctx, mailstack.BulkSendRequest{
	From:    "hello@yourdomain.com",
	Subject: "Hi {{name}}",
	HTML:    "<p>Hello {{name}}</p>",
	Recipients: []mailstack.BulkRecipient{
		{To: "a@example.com", Variables: map[string]any{"name": "Ada"}},
		{To: "b@example.com", Variables: map[string]any{"name": "Bo"}},
	},
})

Scheduled sends and cancellation:

at := time.Now().Add(2 * time.Hour)
resp, _ := client.Emails.Send(ctx, mailstack.SendEmailRequest{ /* ... */, SendAt: &at})
client.Emails.Cancel(ctx, resp.ID) // before it dispatches

Lint is a read-only deliverability + content check (nothing is queued or billed):

result, _ := client.Emails.Lint(ctx, mailstack.SendEmailRequest{ /* ... */ })
fmt.Println(result.Score, result.Rating)

Observability

List messages and read a message's delivery timeline:

msgs, _ := client.Messages.List(ctx, nil, 50) // test=nil → both live & Dev Inbox
events, _ := client.Messages.Events(ctx, msgs[0].ID)
for _, e := range events {
	fmt.Println(e.Type, e.OccurredAt) // Sent, Delivered, Open, Click, ...
}

Domains, templates, API keys

dom, _ := client.Domains.Create(ctx, mailstack.CreateDomainRequest{Domain: "yourdomain.com"})
for _, r := range dom.DNSRecords {
	fmt.Printf("%s %s %s\n", r.Type, r.Name, r.Value) // publish these
}
client.Domains.Verify(ctx, dom.ID)
client.Domains.Blocklist(ctx, dom.ID)

client.Templates.List(ctx)
client.APIKeys.Create(ctx, mailstack.CreateApiKeyRequest{Name: "ci", Scopes: []string{"emails:send"}})

Webhooks

Create a webhook (the signing secret is returned exactly once), then verify incoming deliveries against the raw request body:

res, _ := client.Webhooks.Create(ctx, mailstack.CreateWebhookRequest{
	URL:        "https://example.com/hooks/mailstack",
	EventTypes: "Delivered,Bounce,Complaint",
})
secret := res.SigningSecret // store securely — shown once

func handler(w http.ResponseWriter, r *http.Request) {
	body, _ := io.ReadAll(r.Body) // RAW body — do not re-serialize
	sig := r.Header.Get(mailstack.WebhookSignatureHeader)
	if !mailstack.VerifyWebhookSignature(secret, string(body), sig, 5*time.Minute) {
		w.WriteHeader(http.StatusBadRequest)
		return
	}
	// trusted event
}

The signature is an HMAC-SHA256 over "{timestamp}.{body}" carried in the MailStack-Signature: t=…,v1=… header, compared in constant time.

Errors

Any non-2xx response returns an *APIError with the status code and raw body:

_, err := client.Emails.Send(ctx, req)
var apiErr *mailstack.APIError
if errors.As(err, &apiErr) {
	fmt.Println(apiErr.StatusCode, apiErr.Body)
}

Enums

Status fields arrive as integers and are exposed as typed ints with a friendly String(): MessageStatus, MessageEventType, SendingDomainStatus, TemplateStatus.

License

MIT

Documentation

Overview

Package mailstack is the official Go SDK for the MailStack email API.

Construct a client with your API key and call the resource services hanging off it: 

client := mailstack.New("ms_live_...")
resp, err := client.Emails.Send(ctx, mailstack.SendEmailRequest{
	From:    "hello@yourdomain.com",
	To:      "user@example.com",
	Subject: "Welcome",
	HTML:    "<h1>Hi!</h1>",
})

The send API (Emails) is authorized with an API key. The dashboard-scoped resources (Domains, APIKeys, Templates, Messages, Webhooks) are authorized with a user JWT and require an organization id — pass WithOrgID when constructing the client.

Index

Constants

View Source 
const DefaultBaseURL = "https://api.mailstack.voostack.com"

DefaultBaseURL is the production MailStack API base URL.

View Source 
const WebhookSignatureHeader = "MailStack-Signature"

WebhookSignatureHeader is the header carrying the webhook signature.

Variables

This section is empty.

Functions

func JoinAddresses 

func JoinAddresses(addrs ...string) string

JoinAddresses joins one or more addresses into the comma-separated string the API expects for the to/cc/bcc fields. 

mailstack.JoinAddresses("a@x.com", "b@y.com") // "a@x.com,b@y.com"

func VerifyWebhookSignature 

func VerifyWebhookSignature(secret, payload, signatureHeader string, tolerance time.Duration) bool

VerifyWebhookSignature verifies a MailStack-Signature header against the raw request body.

The signature is an HMAC-SHA256 over "{timestamp}.{body}", compared in constant time. Always pass the RAW body exactly as received — re-serializing JSON changes the bytes and breaks the check.

signatureHeader is the header value, formatted "t=<unix-seconds>,v1=<hex>". tolerance rejects signatures whose timestamp is older than the given duration; pass 0 to skip the freshness check (the default used elsewhere is 5 minutes).

Types

type APIError 

type APIError struct {
	// StatusCode is the HTTP status code of the failed response.
	StatusCode int
	// Body is the raw response body as returned by the API.
	Body string
}

APIError is returned for any non-2xx response from the MailStack API. It carries the HTTP status code and the raw response body (the API's {error,traceId} JSON, when present).

func (*APIError) Error 

func (e *APIError) Error() string

type APIKeysService 

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

APIKeysService manages API keys (/v1/api-keys). Requires an organization id (WithOrgID).

func (*APIKeysService) Create 

func (s *APIKeysService) Create(ctx context.Context, req CreateApiKeyRequest) (ApiKeyCreationResult, error)

Create creates an API key. The returned FullKey is shown exactly once.

func (*APIKeysService) Delete 

func (s *APIKeysService) Delete(ctx context.Context, id string) error

Delete revokes an API key.

func (*APIKeysService) List 

func (s *APIKeysService) List(ctx context.Context) ([]ApiKey, error)

List returns the organization's API keys (never returns secrets).

type ApiKey 

type ApiKey struct {
	ID         string     `json:"id"`
	Name       string     `json:"name"`
	KeyPrefix  string     `json:"keyPrefix"`
	MaskedKey  string     `json:"maskedKey"`
	Scopes     []string   `json:"scopes"`
	LastUsedAt *time.Time `json:"lastUsedAt,omitempty"`
	ExpiresAt  *time.Time `json:"expiresAt,omitempty"`
	RevokedAt  *time.Time `json:"revokedAt,omitempty"`
	IsActive   bool       `json:"isActive"`
	CreatedAt  time.Time  `json:"createdAt"`
}

ApiKey describes an API key (secrets are never returned).

type ApiKeyCreationResult 

type ApiKeyCreationResult struct {
	Key ApiKey `json:"key"`
	// FullKey is the full API key, returned exactly once — store it securely.
	FullKey string `json:"fullKey"`
}

ApiKeyCreationResult is the result of creating a key; FullKey is shown once.

type BatchItemResult 

type BatchItemResult struct {
	Index  int    `json:"index"`
	ID     string `json:"id,omitempty"`
	Status string `json:"status"`
	Error  string `json:"error,omitempty"`
}

BatchItemResult is a per-item result inside a batch/bulk send.

type Block 

type Block struct {
	Type    string         `json:"type"`
	ID      string         `json:"id,omitempty"`
	Padding string         `json:"padding,omitempty"`
	Extra   map[string]any `json:"-"`
}

Block is a builder block. It is polymorphic on Type; per-block fields are carried in Extra.

func (Block) MarshalJSON 

func (b Block) MarshalJSON() ([]byte, error)

MarshalJSON flattens Extra alongside the known fields, matching the API's open block schema (per-block fields live at the top level of each block object).

func (*Block) UnmarshalJSON 

func (b *Block) UnmarshalJSON(data []byte) error

UnmarshalJSON lifts the known fields out and keeps the rest in Extra.

type BlockDocument 

type BlockDocument struct {
	Settings *DocumentSettings `json:"settings,omitempty"`
	Sections []Block           `json:"sections"`
}

BlockDocument is the canonical builder document.

type BlocklistListing 

type BlocklistListing struct {
	Provider string   `json:"provider"`
	Zone     string   `json:"zone"`
	Listed   bool     `json:"listed"`
	Codes    []string `json:"codes"`
	Error    string   `json:"error,omitempty"`
}

BlocklistListing is one blocklist's verdict for a domain.

type BlocklistReport 

type BlocklistReport struct {
	Domain    string             `json:"domain"`
	AnyListed bool               `json:"anyListed"`
	Lists     []BlocklistListing `json:"lists"`
}

BlocklistReport is the aggregate blocklist check for a domain.

type BulkRecipient 

type BulkRecipient struct {
	To        string         `json:"to"`
	Subject   string         `json:"subject,omitempty"`
	Cc        string         `json:"cc,omitempty"`
	Bcc       string         `json:"bcc,omitempty"`
	ReplyTo   string         `json:"replyTo,omitempty"`
	Variables map[string]any `json:"variables,omitempty"`
}

BulkRecipient is one target of a bulk send; its overrides win over the base.

type BulkSendRequest 

type BulkSendRequest struct {
	From       string          `json:"from"`
	FromName   string          `json:"fromName,omitempty"`
	Cc         string          `json:"cc,omitempty"`
	Bcc        string          `json:"bcc,omitempty"`
	ReplyTo    string          `json:"replyTo,omitempty"`
	Subject    string          `json:"subject"`
	HTML       string          `json:"html,omitempty"`
	Text       string          `json:"text,omitempty"`
	TemplateID string          `json:"templateId,omitempty"`
	Variables  map[string]any  `json:"variables,omitempty"`
	Tags       string          `json:"tags,omitempty"`
	Recipients []BulkRecipient `json:"recipients"`
}

BulkSendRequest is a shared base message plus per-recipient overrides.

type Client 

type Client struct {

	// Emails operates on the send API (/v1/emails).
	Emails *EmailsService
	// Messages reads the message log: Activity feed + Dev Inbox (/v1/messages).
	Messages *MessagesService
	// Domains manages sending domains (/v1/domains).
	Domains *DomainsService
	// APIKeys manages API keys (/v1/api-keys).
	APIKeys *APIKeysService
	// Templates manages email templates (/v1/templates).
	Templates *TemplatesService
	// Webhooks manages outbound webhooks + replay (/v1/webhooks).
	Webhooks *WebhooksService
	// contains filtered or unexported fields
}

Client is the MailStack API client. Create one with New.

func New 

func New(apiKey string, opts ...Option) *Client

New creates a MailStack client. The apiKey is sent as a Bearer token on every request.

func (*Client) BaseURL 

func (c *Client) BaseURL() string

BaseURL returns the resolved base URL the client targets.

type CreateApiKeyRequest 

type CreateApiKeyRequest struct {
	Name      string     `json:"name"`
	Scopes    []string   `json:"scopes"`
	ExpiresAt *time.Time `json:"expiresAt,omitempty"`
}

CreateApiKeyRequest creates an API key. Scopes are wire strings such as "emails:send", "domains:read", "templates:read", "templates:write".

type CreateDomainRequest 

type CreateDomainRequest struct {
	Domain string `json:"domain"`
	// MailFromSubdomain is an optional MAIL FROM subdomain override.
	MailFromSubdomain string `json:"mailFromSubdomain,omitempty"`
}

CreateDomainRequest registers a new sending domain.

type CreateTemplateRequest 

type CreateTemplateRequest struct {
	Name      string         `json:"name"`
	Slug      string         `json:"slug,omitempty"`
	Document  BlockDocument  `json:"document"`
	Variables map[string]any `json:"variables,omitempty"`
}

CreateTemplateRequest creates a Draft template.

type CreateWebhookRequest 

type CreateWebhookRequest struct {
	URL        string `json:"url"`
	EventTypes string `json:"eventTypes,omitempty"`
	Enabled    *bool  `json:"enabled,omitempty"`
}

CreateWebhookRequest creates a webhook. EventTypes is a CSV of event-type names or "*"; empty defaults to all events.

type DnsRecord 

type DnsRecord struct {
	Type    string `json:"type"`
	Name    string `json:"name"`
	Value   string `json:"value"`
	TTL     int    `json:"ttl"`
	Purpose string `json:"purpose"`
}

DnsRecord is a DNS record to publish for a sending domain.

type DocumentSettings 

type DocumentSettings struct {
	BackgroundColor string `json:"backgroundColor,omitempty"`
	ContentWidth    int    `json:"contentWidth,omitempty"`
	FontFamily      string `json:"fontFamily,omitempty"`
	PreviewText     string `json:"previewText,omitempty"`
}

DocumentSettings holds document-level template settings.

type DomainsService 

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

DomainsService manages sending domains (/v1/domains). Requires an organization id (WithOrgID).

func (*DomainsService) Blocklist 

func (s *DomainsService) Blocklist(ctx context.Context, id string) (BlocklistReport, error)

Blocklist checks the domain against public blocklists (Spamhaus DBL / SURBL / URIBL).

func (*DomainsService) Create 

func (s *DomainsService) Create(ctx context.Context, req CreateDomainRequest) (SendingDomain, error)

Create registers a new sending domain and returns the DNS records to publish.

func (*DomainsService) Delete 

func (s *DomainsService) Delete(ctx context.Context, id string) error

Delete soft-deletes a sending domain.

func (*DomainsService) Get 

func (s *DomainsService) Get(ctx context.Context, id string) (SendingDomain, error)

Get returns one sending domain, including DNS records + status.

func (*DomainsService) List 

func (s *DomainsService) List(ctx context.Context) ([]SendingDomain, error)

List returns the organization's sending domains.

func (*DomainsService) Verify 

func (s *DomainsService) Verify(ctx context.Context, id string) (SendingDomain, error)

Verify re-checks a domain's verification status with the provider.

type EmailsService 

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

EmailsService operates on the send API (/v1/emails). Authorized with an API key.

func (*EmailsService) Bulk 

func (s *EmailsService) Bulk(ctx context.Context, req BulkSendRequest) (SendBatchResponse, error)

Bulk performs a personalized bulk send: one shared base message plus a recipients list with per-recipient overrides (max 100).

func (*EmailsService) Cancel 

func (s *EmailsService) Cancel(ctx context.Context, id string) (Message, error)

Cancel cancels a future-dated (scheduled) message before it dispatches.

func (*EmailsService) Get 

func (s *EmailsService) Get(ctx context.Context, id string) (Message, error)

Get returns a message and its current status by id.

func (*EmailsService) Lint 

func (s *EmailsService) Lint(ctx context.Context, req SendEmailRequest) (LintResult, error)

Lint runs a read-only pre-send deliverability + content health check. Nothing is queued or billed.

func (*EmailsService) List 

func (s *EmailsService) List(ctx context.Context, test *bool, limit int) ([]Message, error)

List returns recent messages (newest first). test filters live vs Dev Inbox (pass nil for both); limit is clamped server-side (default 50).

func (*EmailsService) Send 

func (s *EmailsService) Send(ctx context.Context, req SendEmailRequest) (SendEmailResponse, error)

Send queues a single email. Resolves with the message id + status (HTTP 202).

func (*EmailsService) SendBatch 

func (s *EmailsService) SendBatch(ctx context.Context, emails []SendEmailRequest) (SendBatchResponse, error)

SendBatch queues a batch of fully-specified emails (max 100) and returns per-item results.

type LintAuth 

type LintAuth struct {
	Domain          string `json:"domain,omitempty"`
	DomainVerified  bool   `json:"domainVerified"`
	DKIM            bool   `json:"dkim"`
	AlignedMailFrom bool   `json:"alignedMailFrom"`
}

LintAuth is the authentication portion of a lint result.

type LintIssue 

type LintIssue struct {
	// Severity is "error", "warning", or "info".
	Severity string `json:"severity"`
	// Code is a stable machine code, e.g. "BODY_NO_TEXT".
	Code    string `json:"code"`
	Message string `json:"message"`
	Fix     string `json:"fix,omitempty"`
}

LintIssue is a single finding from a pre-send lint.

type LintResult 

type LintResult struct {
	// Score is a 0–100 health score.
	Score int `json:"score"`
	// Rating is "good", "needs-work", or "poor".
	Rating string `json:"rating"`
	// Passed is true when there are no error-severity issues.
	Passed         bool        `json:"passed"`
	Authentication LintAuth    `json:"authentication"`
	Issues         []LintIssue `json:"issues"`
}

LintResult is the outcome of a pre-send lint (read-only, never billed).

type Message 

type Message struct {
	ID                string        `json:"id"`
	FromEmail         string        `json:"fromEmail"`
	FromName          string        `json:"fromName,omitempty"`
	ToEmail           string        `json:"toEmail"`
	Cc                string        `json:"cc,omitempty"`
	Bcc               string        `json:"bcc,omitempty"`
	ReplyTo           string        `json:"replyTo,omitempty"`
	Subject           string        `json:"subject"`
	Status            MessageStatus `json:"status"`
	ProviderMessageID string        `json:"providerMessageId,omitempty"`
	ErrorMessage      string        `json:"errorMessage,omitempty"`
	Tags              string        `json:"tags,omitempty"`
	QueuedAt          time.Time     `json:"queuedAt"`
	SentAt            *time.Time    `json:"sentAt,omitempty"`
	CreatedAt         time.Time     `json:"createdAt"`
}

Message is a queued/sent message with its current status.

type MessageDetail 

type MessageDetail struct {
	Message  Message `json:"message"`
	HTMLBody string  `json:"htmlBody,omitempty"`
	TextBody string  `json:"textBody,omitempty"`
}

MessageDetail is a message plus its rendered bodies.

type MessageEvent 

type MessageEvent struct {
	ID         string           `json:"id"`
	Type       MessageEventType `json:"type"`
	OccurredAt time.Time        `json:"occurredAt"`
	Metadata   json.RawMessage  `json:"metadata,omitempty"`
}

MessageEvent is one row of a message's delivery timeline. Metadata is the raw JSON metadata (clicked link, bounce subtype, UA/IP …).

type MessageEventType 

type MessageEventType int

MessageEventType is a provider event in a message's delivery timeline. 

const (
	MessageEventTypeSent          MessageEventType = 0
	MessageEventTypeDelivered     MessageEventType = 1
	MessageEventTypeBounce        MessageEventType = 2
	MessageEventTypeComplaint     MessageEventType = 3
	MessageEventTypeOpen          MessageEventType = 4
	MessageEventTypeClick         MessageEventType = 5
	MessageEventTypeReject        MessageEventType = 6
	MessageEventTypeDeliveryDelay MessageEventType = 7
)

func (MessageEventType) String 

func (t MessageEventType) String() string

type MessageStatus 

type MessageStatus int

MessageStatus is the lifecycle of an outbound message. 

const (
	MessageStatusQueued     MessageStatus = 0
	MessageStatusSending    MessageStatus = 1
	MessageStatusSent       MessageStatus = 2
	MessageStatusDelivered  MessageStatus = 3
	MessageStatusBounced    MessageStatus = 4
	MessageStatusComplained MessageStatus = 5
	MessageStatusFailed     MessageStatus = 6
	MessageStatusScheduled  MessageStatus = 7
	MessageStatusCanceled   MessageStatus = 8
)

func (MessageStatus) String 

func (s MessageStatus) String() string

type MessagesService 

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

MessagesService reads the org-scoped message log (/v1/messages): the Activity feed and the Dev Inbox. Requires an organization id (WithOrgID).

func (*MessagesService) Events 

func (s *MessagesService) Events(ctx context.Context, id string) ([]MessageEvent, error)

Events returns a message's delivery timeline — the ordered provider events (sent, delivered, opened, clicked, bounced …) for end-to-end observability.

func (*MessagesService) Get 

func (s *MessagesService) Get(ctx context.Context, id string) (MessageDetail, error)

Get returns one message with its rendered HTML/text bodies.

func (*MessagesService) List 

func (s *MessagesService) List(ctx context.Context, test *bool, limit int) ([]Message, error)

List returns recent messages (newest first). test filters live vs Dev Inbox (pass nil for both); limit is clamped server-side (default 50).

type Option 

type Option func(*Client)

Option configures a Client.

func WithBaseURL 

func WithBaseURL(baseURL string) Option

WithBaseURL overrides the API base URL (default DefaultBaseURL).

func WithHTTPClient 

func WithHTTPClient(h *http.Client) Option

WithHTTPClient supplies a custom *http.Client (for timeouts, proxies, tests).

func WithOrgID 

func WithOrgID(orgID string) Option

WithOrgID sets the organization id (VooStackOrganizationId) sent as the X-MailStack-Org header, required for the dashboard-scoped resources.

type PreviewResult 

type PreviewResult struct {
	Mjml   string   `json:"mjml"`
	HTML   string   `json:"html"`
	Errors []string `json:"errors"`
}

PreviewResult is the compiled output of a template preview.

type PreviewTemplateRequest 

type PreviewTemplateRequest struct {
	// Document, when set, is compiled and takes precedence over TemplateID.
	Document *BlockDocument `json:"document,omitempty"`
	// TemplateID compiles a stored template's document instead.
	TemplateID string `json:"templateId,omitempty"`
	// Variables are sample values for the substitution preview.
	Variables map[string]any `json:"variables,omitempty"`
}

PreviewTemplateRequest compiles a supplied document or a stored template.

type SendBatchResponse 

type SendBatchResponse struct {
	Accepted int               `json:"accepted"`
	Rejected int               `json:"rejected"`
	Results  []BatchItemResult `json:"results"`
}

SendBatchResponse is the result of a batch or bulk send.

type SendEmailRequest 

type SendEmailRequest struct {
	// From is the sender address; its domain must be a Verified sending domain.
	From string `json:"from"`
	// FromName is the optional sender display name.
	FromName string `json:"fromName,omitempty"`
	// To is the recipient address list (comma-separated).
	To string `json:"to"`
	// Cc is the CC address list (comma-separated).
	Cc string `json:"cc,omitempty"`
	// Bcc is the BCC address list (comma-separated).
	Bcc string `json:"bcc,omitempty"`
	// ReplyTo is the Reply-To address.
	ReplyTo string `json:"replyTo,omitempty"`
	// Subject is the email subject.
	Subject string `json:"subject"`
	// HTML is the HTML body (provide HTML and/or Text, or a TemplateID).
	HTML string `json:"html,omitempty"`
	// Text is the plain-text body.
	Text string `json:"text,omitempty"`
	// TemplateID renders a published template instead of inline bodies.
	TemplateID string `json:"templateId,omitempty"`
	// Variables are values for inline/template substitution.
	Variables map[string]any `json:"variables,omitempty"`
	// Tags is an optional comma-separated tag list.
	Tags string `json:"tags,omitempty"`
	// SendAt, when in the future, holds the message (status Scheduled) and
	// dispatches it then; cancel with Emails.Cancel. Ignored by test-mode keys.
	SendAt *time.Time `json:"sendAt,omitempty"`
}

SendEmailRequest is a single email to send. The To, Cc, and Bcc fields are comma-separated address lists — use JoinAddresses to build them from a slice.

type SendEmailResponse 

type SendEmailResponse struct {
	ID     string `json:"id"`
	Status string `json:"status"`
}

SendEmailResponse is returned when a single email is accepted (HTTP 202).

type SendingDomain 

type SendingDomain struct {
	ID                   string              `json:"id"`
	Domain               string              `json:"domain"`
	Status               SendingDomainStatus `json:"status"`
	CustomMailFromDomain string              `json:"customMailFromDomain,omitempty"`
	LastCheckedAt        *time.Time          `json:"lastCheckedAt,omitempty"`
	VerifiedAt           *time.Time          `json:"verifiedAt,omitempty"`
	CreatedAt            time.Time           `json:"createdAt"`
	DNSRecords           []DnsRecord         `json:"dnsRecords"`
}

SendingDomain is a registered sending domain plus its DNS records and status.

type SendingDomainStatus 

type SendingDomainStatus int

SendingDomainStatus is the verification lifecycle of a sending domain. 

const (
	SendingDomainStatusNotStarted SendingDomainStatus = 0
	SendingDomainStatusPending    SendingDomainStatus = 1
	SendingDomainStatusVerified   SendingDomainStatus = 2
	SendingDomainStatusFailed     SendingDomainStatus = 3
)

func (SendingDomainStatus) String 

func (s SendingDomainStatus) String() string

type Template 

type Template struct {
	ID           string         `json:"id"`
	Name         string         `json:"name"`
	Slug         string         `json:"slug,omitempty"`
	Status       TemplateStatus `json:"status"`
	Version      int            `json:"version"`
	Document     *BlockDocument `json:"document,omitempty"`
	MjmlSource   string         `json:"mjmlSource,omitempty"`
	CompiledHTML string         `json:"compiledHtml,omitempty"`
	Variables    map[string]any `json:"variables,omitempty"`
	CreatedAt    time.Time      `json:"createdAt"`
	ModifiedAt   *time.Time     `json:"modifiedAt,omitempty"`
}

Template is a full email template (document + generated MJML/HTML).

type TemplateStatus 

type TemplateStatus int

TemplateStatus is the lifecycle state of an email template. 

const (
	TemplateStatusDraft     TemplateStatus = 0
	TemplateStatusPublished TemplateStatus = 1
)

func (TemplateStatus) String 

func (s TemplateStatus) String() string

type TemplateSummary 

type TemplateSummary struct {
	ID         string         `json:"id"`
	Name       string         `json:"name"`
	Slug       string         `json:"slug,omitempty"`
	Status     TemplateStatus `json:"status"`
	Version    int            `json:"version"`
	CreatedAt  time.Time      `json:"createdAt"`
	ModifiedAt *time.Time     `json:"modifiedAt,omitempty"`
}

TemplateSummary is the lightweight list-item shape from Templates.List.

type TemplatesService 

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

TemplatesService manages email templates (/v1/templates). Requires an organization id (WithOrgID).

func (*TemplatesService) Create 

func (s *TemplatesService) Create(ctx context.Context, req CreateTemplateRequest) (Template, error)

Create creates a Draft template.

func (*TemplatesService) Delete 

func (s *TemplatesService) Delete(ctx context.Context, id string) error

Delete soft-deletes a template.

func (*TemplatesService) Get 

func (s *TemplatesService) Get(ctx context.Context, id string) (Template, error)

Get returns one template (document + generated MJML/HTML).

func (*TemplatesService) List 

func (s *TemplatesService) List(ctx context.Context) ([]TemplateSummary, error)

List returns the organization's templates (summary view).

func (*TemplatesService) Preview 

func (s *TemplatesService) Preview(ctx context.Context, req PreviewTemplateRequest) (PreviewResult, error)

Preview compiles a supplied document or stored template (no persistence).

func (*TemplatesService) Publish 

func (s *TemplatesService) Publish(ctx context.Context, id string) (Template, error)

Publish publishes a template (Draft -> Published) so the send API can use it.

func (*TemplatesService) Update 

func (s *TemplatesService) Update(ctx context.Context, id string, req UpdateTemplateRequest) (Template, error)

Update replaces a template's content (regenerates MJML+HTML, bumps version).

type UpdateTemplateRequest 

type UpdateTemplateRequest struct {
	Name      string         `json:"name"`
	Slug      string         `json:"slug,omitempty"`
	Document  BlockDocument  `json:"document"`
	Variables map[string]any `json:"variables,omitempty"`
}

UpdateTemplateRequest replaces a template's content (bumps version).

type UpdateWebhookRequest 

type UpdateWebhookRequest struct {
	URL        string `json:"url"`
	EventTypes string `json:"eventTypes,omitempty"`
	Enabled    *bool  `json:"enabled,omitempty"`
}

UpdateWebhookRequest updates a webhook's URL, events, and enabled flag.

type Webhook 

type Webhook struct {
	ID  string `json:"id"`
	URL string `json:"url"`
	// EventTypes is a CSV of event-type names, or "*".
	EventTypes     string     `json:"eventTypes"`
	Enabled        bool       `json:"enabled"`
	SecretHint     string     `json:"secretHint"`
	LastDeliveryAt *time.Time `json:"lastDeliveryAt,omitempty"`
	LastStatusCode *int       `json:"lastStatusCode,omitempty"`
	CreatedAt      time.Time  `json:"createdAt"`
}

Webhook is an outbound webhook subscription (secret masked).

type WebhookDelivery 

type WebhookDelivery struct {
	ID             string     `json:"id"`
	WebhookID      string     `json:"webhookId"`
	MessageEventID string     `json:"messageEventId"`
	StatusCode     *int       `json:"statusCode,omitempty"`
	Attempt        int        `json:"attempt"`
	Succeeded      bool       `json:"succeeded"`
	Error          string     `json:"error,omitempty"`
	CreatedAt      time.Time  `json:"createdAt"`
	ModifiedAt     *time.Time `json:"modifiedAt,omitempty"`
}

WebhookDelivery is a single delivery attempt of an event to a webhook.

type WebhookSecretResult 

type WebhookSecretResult struct {
	Webhook Webhook `json:"webhook"`
	// SigningSecret is the full whsec_ secret, returned exactly once.
	SigningSecret string `json:"signingSecret"`
}

WebhookSecretResult is returned from create/rotate; SigningSecret is shown once.

type WebhooksService 

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

WebhooksService manages outbound webhooks + replay (/v1/webhooks). Requires an organization id (WithOrgID). Verify incoming deliveries with VerifyWebhookSignature.

func (*WebhooksService) Create 

func (s *WebhooksService) Create(ctx context.Context, req CreateWebhookRequest) (WebhookSecretResult, error)

Create creates a webhook. Returns the full signing secret exactly once.

func (*WebhooksService) Delete 

func (s *WebhooksService) Delete(ctx context.Context, id string) error

Delete soft-deletes a webhook.

func (*WebhooksService) Deliveries 

func (s *WebhooksService) Deliveries(ctx context.Context, id string, limit int) ([]WebhookDelivery, error)

Deliveries returns recent delivery attempts for a webhook (newest first). limit is clamped server-side (default 50).

func (*WebhooksService) Get 

func (s *WebhooksService) Get(ctx context.Context, id string) (Webhook, error)

Get returns one webhook by id (secret masked).

func (*WebhooksService) List 

func (s *WebhooksService) List(ctx context.Context) ([]Webhook, error)

List returns the org's webhooks (secrets masked).

func (*WebhooksService) Replay 

func (s *WebhooksService) Replay(ctx context.Context, deliveryID string) (WebhookDelivery, error)

Replay re-enqueues the same (webhook, event) for delivery.

func (*WebhooksService) RotateSecret 

func (s *WebhooksService) RotateSecret(ctx context.Context, id string) (WebhookSecretResult, error)

RotateSecret rotates the signing secret. Returns the new full secret once.

func (*WebhooksService) Update 

func (s *WebhooksService) Update(ctx context.Context, id string, req UpdateWebhookRequest) (Webhook, error)

Update updates a webhook's URL, subscribed events, and enabled flag.

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.