axene

package module
v0.1.0 Latest Latest
Warning

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

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

README

Axene Mailer Go SDK

Official Go client for the Axene Mailer API: email sending, domains, contacts, suppressions, templates, and webhooks.

Stdlib only. Go 1.21+. MIT licensed.

Install

go get github.com/Axene-Solutions/axene-mailer-go

import axene "github.com/Axene-Solutions/axene-mailer-go"

Quickstart

package main

import (
	"context"
	"log"

	axene "github.com/Axene-Solutions/axene-mailer-go"
)

func main() {
	client := axene.New("axm_k_...")

	resp, err := client.Emails.Send(context.Background(), axene.SendEmail{
		From:    axene.Addr("hello@yourdomain.com"),
		To:      []axene.Address{axene.Addr("customer@example.com")},
		Subject: "Your receipt",
		HTML:    "<p>Thanks for your order.</p>",
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("queued %s (%s)", resp.ID, resp.Status)
}

A sender or recipient is an Address. Use axene.Addr("a@b.io") for the common case, or build one with a display name:

axene.Address{Email: "a@b.io", Name: "Support"}

Configuration

New takes the API key and optional functional options:

client := axene.New(
	"axm_k_...",
	axene.WithBaseURL("https://mail.axene.io"), // default
	axene.WithMaxRetries(3),                    // default
	axene.WithTimeout(30*time.Second),          // default
	axene.WithHTTPClient(myHTTPClient),         // optional
)

The client retries 429 and 5xx responses with exponential backoff, honoring the Retry-After header. It never retries other 4xx responses.

Errors

Every method returns an error that is a *axene.Error on a non-2xx response or a transport failure:

_, err := client.Emails.Send(ctx, msg)
if err != nil {
	var ae *axene.Error
	if errors.As(err, &ae) {
		log.Printf("status=%d code=%s message=%s", ae.Status, ae.Code, ae.Message)
	}
}

Status is 0 for a network/transport failure with no HTTP response.

Resources

  • client.Emails - Send, SendBatch, Validate, List, Get, Events, Retry, Search, ListScheduled, CancelScheduled, SendScheduledNow, Updates, GetSavedSearches, SetSavedSearches.
  • client.Domains - List, Create, Get, Delete, Verify, Health, Diagnose, MxStatus, PublishedRecords, RotateDkim, Transfer, CheckAvailability, Check.
  • client.Contacts - ListLists, CreateList, GetList, UpdateList, DeleteList, AddContact, RemoveContact, UploadCSV, BulkSend.
  • client.Suppressions - List, Add, BulkUpload, Remove.
  • client.Templates - List, Create, Get, Update, Delete, Duplicate.
  • client.Webhooks - List, Create, Update, Delete, Test, ListDeliveries, GetDelivery.
Pagination

Pagination is zero-based: Page: 0 is the first page. Most list endpoints return a bare slice. Suppressions list and webhook deliveries return a Page[T] envelope:

page, _ := client.Suppressions.List(ctx, axene.ListSuppressionsParams{Page: 0, Limit: 50})
for _, s := range page.Items {
	log.Println(s.EmailAddress)
}
log.Printf("%d total", page.Total)
CSV uploads

Contacts.UploadCSV and Suppressions.BulkUpload send the file as multipart/form-data under the field name file:

data, _ := os.ReadFile("contacts.csv")
res, _ := client.Contacts.UploadCSV(ctx, listID, data, "contacts.csv")
log.Printf("imported %d, skipped %d", res.Imported, res.Skipped)

Not yet covered

The advanced domain endpoints (ns-provider, BIMI, domain-connect) are not wrapped in this version.

License

MIT

Documentation

Overview

Package axene is the official Go client for the Axene Mailer API.

Axene Mailer is an email marketing and transactional sending platform. This package wraps the REST API at https://mail.axene.io behind a small, typed client. Construct a client with an API key (it starts with axm_k_) and reach the API through resource fields: 

client := axene.New("axm_k_...")
resp, err := client.Emails.Send(ctx, axene.SendEmail{
	From:    axene.Addr("hello@yourdomain.com"),
	To:      []axene.Address{axene.Addr("customer@example.com")},
	Subject: "Your receipt",
	HTML:    "<p>Thanks for your order.</p>",
})

The client owns one transport layer (transport.go) that handles bearer authentication, JSON encoding, the from -> from_ wire mapping, retries on 429 and 5xx with backoff (honoring Retry-After), and error mapping to *Error. Resource types (Emails, Domains, Contacts, Suppressions, Templates, Webhooks) are thin and delegate to that transport. Every method takes a context.Context as its first argument.

Pagination is zero-based: page 0 is the first page. Most list endpoints return a bare slice; suppressions list and webhook deliveries return a Page[T] envelope.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AddContactParams 

type AddContactParams struct {
	Email    string         `json:"email"`
	Name     *string        `json:"name,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

AddContactParams is the body for Contacts.AddContact.

type AddSuppressionParams 

type AddSuppressionParams struct {
	Email  string `json:"email_address"`
	Reason string `json:"reason,omitempty"`
}

AddSuppressionParams is the body for Suppressions.Add. Email maps to the wire field email_address.

type Address 

type Address struct {
	Email string `json:"email"`
	Name  string `json:"name,omitempty"`
}

Address is a recipient or sender. Email is required; Name is optional. Use Addr to build one from a bare email string.

func Addr 

func Addr(email string) Address

Addr is a helper that builds an Address from a bare email string.

type Attachment 

type Attachment struct {
	Filename      string `json:"filename"`
	ContentBase64 string `json:"content_base64"`
	ContentType   string `json:"content_type,omitempty"`
}

Attachment is a file attached to an email. ContentBase64 is the raw base64 content with no "data:" prefix.

type BatchResult 

type BatchResult struct {
	Total   int          `json:"total"`
	Sent    int          `json:"sent"`
	Failed  int          `json:"failed"`
	Results []SendResult `json:"results"`
}

BatchResult is the result of Emails.SendBatch.

type BulkSendParams 

type BulkSendParams struct {
	ContactListID   string   `json:"contact_list_id,omitempty"`
	SenderAddressID string   `json:"sender_address_id"`
	Subject         string   `json:"subject"`
	HTML            string   `json:"html,omitempty"`
	Text            string   `json:"text,omitempty"`
	Tags            []string `json:"tags,omitempty"`
}

BulkSendParams is the body for Contacts.BulkSend. ContactListID is injected automatically from the list id by BulkSend, so callers leave it unset.

type BulkSendResult 

type BulkSendResult struct {
	Queued  int      `json:"queued"`
	Skipped int      `json:"skipped"`
	Errors  []string `json:"errors"`
}

BulkSendResult is the result of Contacts.BulkSend.

type BulkSuppressionResult 

type BulkSuppressionResult struct {
	Added          int `json:"added"`
	Skipped        int `json:"skipped"`
	TotalProcessed int `json:"total_processed"`
}

BulkSuppressionResult is the result of Suppressions.BulkUpload.

type Client 

type Client struct {
	// Emails sends, searches, schedules, and inspects messages.
	Emails *Emails
	// Domains registers, verifies, and transfers sending domains.
	Domains *Domains
	// Contacts manages subscriber lists and bulk sends.
	Contacts *Contacts
	// Suppressions manages the do-not-send list.
	Suppressions *Suppressions
	// Templates manages reusable email templates.
	Templates *Templates
	// Webhooks manages event webhooks and inspects deliveries.
	Webhooks *Webhooks
	// contains filtered or unexported fields
}

Client is the Axene Mailer API client. Construct it with New and reach the API through its resource fields. Client is safe for concurrent use.

func New 

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

New constructs a Client. apiKey is required and starts with axm_k_.

type Contact 

type Contact struct {
	ID        string         `json:"id"`
	Email     string         `json:"email"`
	Name      string         `json:"name,omitempty"`
	Metadata  map[string]any `json:"metadata,omitempty"`
	CreatedAt string         `json:"created_at"`
}

Contact is a single contact in a list.

type ContactList 

type ContactList struct {
	ID           string `json:"id"`
	Name         string `json:"name"`
	Description  string `json:"description,omitempty"`
	IconSeed     string `json:"icon_seed,omitempty"`
	ContactCount int    `json:"contact_count"`
	CreatedAt    string `json:"created_at"`
}

ContactList is a subscriber list.

type ContactListDetail 

type ContactListDetail struct {
	ContactList
	Contacts []Contact `json:"contacts"`
}

ContactListDetail is a contact list with a page of its contacts.

type Contacts 

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

Contacts is the contacts resource, reached as client.Contacts.

func (*Contacts) AddContact 

func (c *Contacts) AddContact(ctx context.Context, listID string, params AddContactParams) (*Contact, error)

AddContact adds a single contact to a list.

func (*Contacts) BulkSend 

func (c *Contacts) BulkSend(ctx context.Context, listID string, params BulkSendParams) (*BulkSendResult, error)

BulkSend sends a templated email to every contact in a list. The list id is injected as contact_list_id automatically. Subject/HTML/Text may use {{email}}, {{name}}, and {{metadata_key}} placeholders.

func (*Contacts) CreateList 

func (c *Contacts) CreateList(ctx context.Context, params CreateListParams) (*ContactList, error)

CreateList creates a subscriber list.

func (*Contacts) DeleteList 

func (c *Contacts) DeleteList(ctx context.Context, id string) error

DeleteList deletes a list and all of its contacts.

func (*Contacts) GetList 

func (c *Contacts) GetList(ctx context.Context, id string, params ListContactsParams) (*ContactListDetail, error)

GetList gets a list with a page of its contacts (zero-based page).

func (*Contacts) ListLists 

func (c *Contacts) ListLists(ctx context.Context) ([]ContactList, error)

ListLists returns all subscriber lists in the active workspace.

func (*Contacts) RemoveContact 

func (c *Contacts) RemoveContact(ctx context.Context, listID, contactID string) error

RemoveContact removes a contact from a list.

func (*Contacts) UpdateList 

func (c *Contacts) UpdateList(ctx context.Context, id string, params UpdateListParams) (*ContactList, error)

UpdateList updates a list's name, description, or icon (partial).

func (*Contacts) UploadCSV 

func (c *Contacts) UploadCSV(ctx context.Context, listID string, file []byte, filename string) (*CsvImportResult, error)

UploadCSV imports contacts from a CSV file (header row required). The upload is sent as multipart/form-data under the field name "file".

type CreateListParams 

type CreateListParams struct {
	Name        string  `json:"name"`
	Description *string `json:"description,omitempty"`
	IconSeed    *string `json:"icon_seed,omitempty"`
}

CreateListParams is the body for Contacts.CreateList. IconSeed maps to the wire field icon_seed. Use pointers so unset fields are omitted.

type CreateTemplateParams 

type CreateTemplateParams struct {
	Name       string         `json:"name"`
	Subject    *string        `json:"subject,omitempty"`
	HTML       *string        `json:"html_body,omitempty"`
	Text       *string        `json:"text_body,omitempty"`
	BlocksJSON map[string]any `json:"blocks_json,omitempty"`
}

CreateTemplateParams is the body for Templates.Create. HTML maps to html_body and Text maps to text_body.

type CreateWebhookParams 

type CreateWebhookParams struct {
	URL    string   `json:"url"`
	Events []string `json:"events"`
}

CreateWebhookParams is the body for Webhooks.Create.

type CsvImportResult 

type CsvImportResult struct {
	Imported int      `json:"imported"`
	Skipped  int      `json:"skipped"`
	Errors   []string `json:"errors"`
}

CsvImportResult is the result of Contacts.UploadCSV.

type DkimRotation 

type DkimRotation struct {
	DkimRecordHost  string `json:"dkim_record_host"`
	DkimRecordValue string `json:"dkim_record_value"`
	Domain          Domain `json:"domain"`
}

DkimRotation is the result of Domains.RotateDkim: the new record and domain.

type DnsRecord 

type DnsRecord struct {
	ID            string `json:"id"`
	RecordType    string `json:"record_type"`
	Purpose       string `json:"purpose"`
	Host          string `json:"host"`
	Value         string `json:"value"`
	IsVerified    bool   `json:"is_verified"`
	LastCheckedAt string `json:"last_checked_at,omitempty"`
}

DnsRecord is a DNS record the API expects you to publish for a domain.

type Domain 

type Domain struct {
	ID              string      `json:"id"`
	Name            string      `json:"name"`
	Status          string      `json:"status"`
	DkimSelector    string      `json:"dkim_selector"`
	VerifiedAt      string      `json:"verified_at,omitempty"`
	CreatedAt       string      `json:"created_at,omitempty"`
	DnsRecords      []DnsRecord `json:"dns_records"`
	PlatformWarning string      `json:"platform_warning,omitempty"`
}

Domain is a sending domain with its DKIM selector and DNS records.

type DomainAvailability 

type DomainAvailability struct {
	Available   bool   `json:"available"`
	Reason      string `json:"reason,omitempty"`
	Detail      string `json:"detail,omitempty"`
	StaleTokens *int   `json:"stale_tokens,omitempty"`
}

DomainAvailability is the result of Domains.CheckAvailability.

type DomainCheck 

type DomainCheck struct {
	Exists   bool   `json:"exists"`
	Verified bool   `json:"verified"`
	Status   string `json:"status,omitempty"`
	Domain   string `json:"domain"`
	ID       string `json:"id,omitempty"`
}

DomainCheck is the result of Domains.Check.

type DomainDiagnosis 

type DomainDiagnosis struct {
	Domain      string           `json:"domain"`
	Issues      []map[string]any `json:"issues"`
	HealthScore int              `json:"health_score"`
}

DomainDiagnosis is the result of Domains.Diagnose. Issue shapes vary.

type DomainHealth 

type DomainHealth struct {
	Domain  string              `json:"domain"`
	Checks  []DomainHealthCheck `json:"checks"`
	Summary DomainHealthSummary `json:"summary"`
}

DomainHealth is the result of Domains.Health.

type DomainHealthCheck 

type DomainHealthCheck struct {
	Key            string              `json:"key"`
	Label          string              `json:"label"`
	Status         string              `json:"status"`
	Detail         string              `json:"detail"`
	Recommendation string              `json:"recommendation,omitempty"`
	Record         *DomainHealthRecord `json:"record,omitempty"`
}

DomainHealthCheck is one row of a domain health report.

type DomainHealthRecord 

type DomainHealthRecord struct {
	Type  string `json:"type"`
	Host  string `json:"host"`
	Value string `json:"value"`
}

DomainHealthRecord is the optional DNS record on a health check row.

type DomainHealthSummary 

type DomainHealthSummary struct {
	OK    int `json:"ok"`
	Warn  int `json:"warn"`
	Error int `json:"error"`
	Info  int `json:"info"`
}

DomainHealthSummary is the tally of check statuses in a health report.

type DomainListItem 

type DomainListItem struct {
	ID              string `json:"id"`
	Name            string `json:"name"`
	Status          string `json:"status"`
	CreatedAt       string `json:"created_at,omitempty"`
	PlatformWarning string `json:"platform_warning,omitempty"`
}

DomainListItem is a row from Domains.List.

type DomainTransfer 

type DomainTransfer struct {
	ID           string `json:"id"`
	DomainID     string `json:"domain_id"`
	DomainName   string `json:"domain_name,omitempty"`
	SourceUserID string `json:"source_user_id,omitempty"`
	SourceOrgID  string `json:"source_org_id,omitempty"`
	SourceLabel  string `json:"source_label,omitempty"`
	TargetEmail  string `json:"target_email"`
	TargetUserID string `json:"target_user_id,omitempty"`
	TargetOrgID  string `json:"target_org_id,omitempty"`
	Status       string `json:"status"`
	Note         string `json:"note,omitempty"`
	CooloffUntil string `json:"cooloff_until,omitempty"`
	InitiatedAt  string `json:"initiated_at"`
	AcceptedAt   string `json:"accepted_at,omitempty"`
	CompletedAt  string `json:"completed_at,omitempty"`
	ExpiresAt    string `json:"expires_at"`
}

DomainTransfer is a domain transfer record returned by Domains.Transfer.

type Domains 

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

Domains is the domains resource, reached as client.Domains.

func (*Domains) Check 

func (d *Domains) Check(ctx context.Context, name string) (*DomainCheck, error)

Check checks whether a domain name already exists in your account.

func (*Domains) CheckAvailability 

func (d *Domains) CheckAvailability(ctx context.Context, name string) (*DomainAvailability, error)

CheckAvailability checks whether a domain name is available to add.

func (*Domains) Create 

func (d *Domains) Create(ctx context.Context, name string) (*Domain, error)

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

func (*Domains) Delete 

func (d *Domains) Delete(ctx context.Context, id string) error

Delete deletes a domain.

func (*Domains) Diagnose 

func (d *Domains) Diagnose(ctx context.Context, id string) (*DomainDiagnosis, error)

Diagnose diagnoses configuration issues and returns a health score.

func (*Domains) Get 

func (d *Domains) Get(ctx context.Context, id string) (*Domain, error)

Get fetches a domain with its DKIM selector and DNS records.

func (*Domains) Health 

func (d *Domains) Health(ctx context.Context, id string) (*DomainHealth, error)

Health runs live DNS health checks (DKIM, SPF, DMARC, return-path, MX).

func (*Domains) List 

func (d *Domains) List(ctx context.Context) ([]DomainListItem, error)

List returns your sending domains and their verification status.

func (*Domains) MxStatus 

func (d *Domains) MxStatus(ctx context.Context, id string) (map[string]any, error)

MxStatus returns the current MX status (shape varies by provider).

func (*Domains) PublishedRecords 

func (d *Domains) PublishedRecords(ctx context.Context, id string) (map[string]any, error)

PublishedRecords returns the values currently published in DNS for each of the domain's records (an open map).

func (*Domains) RotateDkim 

func (d *Domains) RotateDkim(ctx context.Context, id string) (*DkimRotation, error)

RotateDkim rotates the domain's DKIM key, returning the new record to publish.

func (*Domains) Transfer 

func (d *Domains) Transfer(ctx context.Context, id string, params TransferParams) (*DomainTransfer, error)

Transfer initiates a transfer of this domain to another Axene account.

func (*Domains) Verify 

func (d *Domains) Verify(ctx context.Context, id string) (*Domain, error)

Verify re-checks DNS and verifies the domain.

type Email 

type Email struct {
	ID           string   `json:"id"`
	FromAddress  string   `json:"from_address"`
	ToAddresses  []string `json:"to_addresses"`
	Subject      string   `json:"subject,omitempty"`
	Status       string   `json:"status"`
	Source       string   `json:"source,omitempty"`
	OpenedCount  int      `json:"opened_count"`
	ClickedCount int      `json:"clicked_count"`
	Tags         []string `json:"tags,omitempty"`
	ScheduledAt  string   `json:"scheduled_at,omitempty"`
	CreatedAt    string   `json:"created_at,omitempty"`
	SentAt       string   `json:"sent_at,omitempty"`
	DeliveredAt  string   `json:"delivered_at,omitempty"`
	RetryOfID    string   `json:"retry_of_id,omitempty"`
}

Email is a stored email and its current status.

type EmailDetail 

type EmailDetail struct {
	Email
	CCAddresses  []string       `json:"cc_addresses,omitempty"`
	BCCAddresses []string       `json:"bcc_addresses,omitempty"`
	TextBody     string         `json:"text_body,omitempty"`
	HTMLBody     string         `json:"html_body,omitempty"`
	Headers      map[string]any `json:"headers,omitempty"`
	MessageID    string         `json:"message_id,omitempty"`
	Events       []EmailEvent   `json:"events"`
}

EmailDetail is a stored email with its bodies and events, from Emails.Get.

type EmailEvent 

type EmailEvent struct {
	ID        string         `json:"id"`
	EventType string         `json:"event_type"`
	Metadata  map[string]any `json:"metadata,omitempty"`
	CreatedAt string         `json:"created_at"`
}

EmailEvent is a delivery, open, click, or bounce event for a message.

type EmailSearchHit 

type EmailSearchHit struct {
	ID          string   `json:"id"`
	FromAddress string   `json:"from_address"`
	ToAddresses []string `json:"to_addresses"`
	Subject     string   `json:"subject,omitempty"`
	Status      string   `json:"status"`
	Tags        []string `json:"tags,omitempty"`
	Source      string   `json:"source,omitempty"`
	CreatedAt   string   `json:"created_at,omitempty"`
	DeliveredAt string   `json:"delivered_at,omitempty"`
}

EmailSearchHit is a search result row from Emails.Search.

type Emails 

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

Emails is the emails resource, reached as client.Emails.

func (*Emails) CancelScheduled 

func (e *Emails) CancelScheduled(ctx context.Context, id string) (*IDStatus, error)

CancelScheduled cancels a scheduled email.

func (*Emails) Events 

func (e *Emails) Events(ctx context.Context, id string) ([]EmailEvent, error)

Events lists delivery, open, click, and bounce events for an email.

func (*Emails) Get 

func (e *Emails) Get(ctx context.Context, id string) (*EmailDetail, error)

Get fetches a single email with its bodies and events.

func (*Emails) GetSavedSearches 

func (e *Emails) GetSavedSearches(ctx context.Context) ([]SavedSearch, error)

GetSavedSearches returns the caller's saved email searches.

func (*Emails) List 

func (e *Emails) List(ctx context.Context, params ListEmailsParams) ([]Email, error)

List returns recent emails, newest first.

func (*Emails) ListScheduled 

func (e *Emails) ListScheduled(ctx context.Context) ([]ScheduledEmail, error)

ListScheduled lists emails scheduled for future delivery, soonest first.

func (*Emails) Retry 

func (e *Emails) Retry(ctx context.Context, id string) (*SendResult, error)

Retry re-sends a bounced, rejected, or failed email as a new message.

func (*Emails) Search 

func (e *Emails) Search(ctx context.Context, params SearchEmailsParams) ([]EmailSearchHit, error)

Search searches emails. q supports inline tokens (to:, from:, status:, domain:, tag:); leftover words are matched as free text.

func (*Emails) Send 

func (e *Emails) Send(ctx context.Context, msg SendEmail) (*SendResult, error)

Send sends a single email.

func (*Emails) SendBatch 

func (e *Emails) SendBatch(ctx context.Context, msgs []SendEmail) (*BatchResult, error)

SendBatch sends up to the plan's batch limit in one call. The API accepts a bare array of messages and returns a per-message result set.

func (*Emails) SendScheduledNow 

func (e *Emails) SendScheduledNow(ctx context.Context, id string) (*IDStatus, error)

SendScheduledNow sends a scheduled email immediately instead of waiting.

func (*Emails) SetSavedSearches 

func (e *Emails) SetSavedSearches(ctx context.Context, searches []SavedSearch) ([]SavedSearch, error)

SetSavedSearches replaces the caller's saved email searches (max 50).

func (*Emails) Updates 

func (e *Emails) Updates(ctx context.Context, since string) ([]Email, error)

Updates polls for emails whose status changed at or after since (ISO 8601). The result is capped at 50 rows. since is required.

func (*Emails) Validate 

func (e *Emails) Validate(ctx context.Context, msg SendEmail) (*ValidationResult, error)

Validate dry-runs a send: it checks whether msg would be accepted (sender registered, domain verified, plan limits) without actually sending it.

type Error 

type Error struct {
	// Status is the HTTP status code. 0 indicates a transport or network
	// failure where no response was received.
	Status int
	// Code is the machine-readable error code from the API body, when present.
	Code string
	// Message is a human-readable description of the failure.
	Message string
}

Error is raised for any non-2xx API response, or for a transport failure that survives all retries. Inspect Status and Code to branch on specific failures (for example a 422 with code "invalid").

func (*Error) Error 

func (e *Error) Error() string

Error implements the error interface.

type IDStatus 

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

IDStatus is a minimal {id, status} response (cancel/send-now scheduled).

type ListContactsParams 

type ListContactsParams struct {
	Page  int
	Limit int
}

ListContactsParams are the query parameters for Contacts.GetList.

type ListDeliveriesParams 

type ListDeliveriesParams struct {
	Page   int
	Limit  int
	Status string
}

ListDeliveriesParams are the query parameters for Webhooks.ListDeliveries.

type ListEmailsParams 

type ListEmailsParams struct {
	Status string
	Page   int
	Limit  int
}

ListEmailsParams are the query parameters for Emails.List.

type ListSuppressionsParams 

type ListSuppressionsParams struct {
	Page   int
	Limit  int
	Search string
}

ListSuppressionsParams are the query parameters for Suppressions.List.

type Option 

type Option func(*transport)

Option configures a Client. Pass options to New.

func WithBaseURL 

func WithBaseURL(baseURL string) Option

WithBaseURL overrides the API base URL (default https://mail.axene.io).

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient injects a custom *http.Client (for testing or proxies).

func WithMaxRetries 

func WithMaxRetries(maxRetries int) Option

WithMaxRetries sets the total number of attempts on 429/5xx, including the first (default 3).

func WithTimeout 

func WithTimeout(timeout time.Duration) Option

WithTimeout sets the per-request timeout (default 30s).

type Page 

type Page[T any] struct {
	Items []T `json:"items"`
	Total int `json:"total"`
	Page  int `json:"page"`
	Limit int `json:"limit"`
}

Page is the envelope returned by endpoints that paginate with a total count: suppressions list and webhook deliveries.

type SavedSearch 

type SavedSearch struct {
	ID     string `json:"id,omitempty"`
	Name   string `json:"name,omitempty"`
	Query  string `json:"query,omitempty"`
	Range  string `json:"range,omitempty"`
	Status string `json:"status,omitempty"`
	Domain string `json:"domain,omitempty"`
	Source string `json:"source,omitempty"`
}

SavedSearch is one stored email search. The server normalizes its fields.

type ScheduledEmail 

type ScheduledEmail struct {
	ID               string   `json:"id"`
	FromAddress      string   `json:"from_address"`
	ToAddresses      []string `json:"to_addresses"`
	Subject          string   `json:"subject,omitempty"`
	Status           string   `json:"status"`
	Tags             []string `json:"tags,omitempty"`
	ScheduledAt      string   `json:"scheduled_at,omitempty"`
	SecondsUntilSend int      `json:"seconds_until_send"`
	CreatedAt        string   `json:"created_at,omitempty"`
}

ScheduledEmail is an email awaiting future delivery.

type SearchEmailsParams 

type SearchEmailsParams struct {
	Q      string
	Status string
	Tag    string
	Page   int
	Limit  int
}

SearchEmailsParams are the query parameters for Emails.Search.

type SendEmail 

type SendEmail struct {
	// From is the sender address. It must be on a verified domain.
	From Address `json:"from_"`
	// To is one or more recipients.
	To []Address `json:"to"`
	// Subject is the email subject line.
	Subject string `json:"subject"`
	// HTML is the HTML body. Provide HTML, Text, or both.
	HTML string `json:"html,omitempty"`
	// Text is the plain-text body. Provide HTML, Text, or both.
	Text string `json:"text,omitempty"`
	// CC is an optional list of carbon-copy recipients.
	CC []Address `json:"cc,omitempty"`
	// BCC is an optional list of blind-carbon-copy recipients.
	BCC []Address `json:"bcc,omitempty"`
	// ReplyTo overrides the reply-to address.
	ReplyTo *Address `json:"reply_to,omitempty"`
	// Headers are custom headers to attach to the message.
	Headers map[string]string `json:"headers,omitempty"`
	// Tags label the message for filtering and analytics.
	Tags []string `json:"tags,omitempty"`
	// SendAt schedules delivery for later (ISO 8601). Starter plan and up.
	SendAt string `json:"send_at,omitempty"`
	// Attachments are files to attach to the message.
	Attachments []Attachment `json:"attachments,omitempty"`
}

SendEmail is the body for Emails.Send, Emails.SendBatch, and Emails.Validate. The From field serializes to the wire key "from_" (trailing underscore).

type SendResult 

type SendResult struct {
	ID              string `json:"id"`
	Status          string `json:"status"`
	MessageID       string `json:"message_id,omitempty"`
	RejectionReason string `json:"rejection_reason,omitempty"`
}

SendResult is the result of a send: the queued message id and its status.

type Suppression 

type Suppression struct {
	ID           string `json:"id"`
	EmailAddress string `json:"email_address"`
	Reason       string `json:"reason"`
	CreatedAt    string `json:"created_at,omitempty"`
}

Suppression is a suppressed recipient address.

type Suppressions 

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

Suppressions is the suppressions resource, reached as client.Suppressions.

func (*Suppressions) Add 

func (s *Suppressions) Add(ctx context.Context, params AddSuppressionParams) (*Suppression, error)

Add suppresses a single address. Reason defaults to "manual" when empty.

func (*Suppressions) BulkUpload 

func (s *Suppressions) BulkUpload(ctx context.Context, file []byte, filename string) (*BulkSuppressionResult, error)

BulkUpload imports suppressions from a file (one email per line). The upload is sent as multipart/form-data under the field name "file".

func (*Suppressions) List 

func (s *Suppressions) List(ctx context.Context, params ListSuppressionsParams) (*Page[Suppression], error)

List returns suppressed addresses as a paginated envelope (zero-based page).

func (*Suppressions) Remove 

func (s *Suppressions) Remove(ctx context.Context, id string) error

Remove removes an address from the suppression list.

type Template 

type Template struct {
	ID         string         `json:"id"`
	Name       string         `json:"name"`
	Subject    string         `json:"subject,omitempty"`
	HTMLBody   string         `json:"html_body,omitempty"`
	TextBody   string         `json:"text_body,omitempty"`
	Variables  []string       `json:"variables,omitempty"`
	BlocksJSON map[string]any `json:"blocks_json,omitempty"`
	CreatedAt  string         `json:"created_at"`
	UpdatedAt  string         `json:"updated_at"`
}

Template is a reusable email template. Variables is derived server-side and is read-only.

type Templates 

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

Templates is the templates resource, reached as client.Templates. Templates are available on the Starter plan and up.

func (*Templates) Create 

func (t *Templates) Create(ctx context.Context, params CreateTemplateParams) (*Template, error)

Create creates a template. Variables are derived server-side from {{name}} placeholders, so you do not pass them.

func (*Templates) Delete 

func (t *Templates) Delete(ctx context.Context, id string) error

Delete deletes a template.

func (*Templates) Duplicate 

func (t *Templates) Duplicate(ctx context.Context, id string) (*Template, error)

Duplicate duplicates a template. The copy's blocks_json is not carried over.

func (*Templates) Get 

func (t *Templates) Get(ctx context.Context, id string) (*Template, error)

Get fetches a single template.

func (*Templates) List 

func (t *Templates) List(ctx context.Context) ([]Template, error)

List returns all templates, most recently updated first.

func (*Templates) Update 

func (t *Templates) Update(ctx context.Context, id string, params UpdateTemplateParams) (*Template, error)

Update updates a template (partial).

type TransferParams 

type TransferParams struct {
	TargetEmail string `json:"target_email"`
	Note        string `json:"note,omitempty"`
}

TransferParams is the body for Domains.Transfer.

type UpdateListParams 

type UpdateListParams struct {
	Name        *string `json:"name,omitempty"`
	Description *string `json:"description,omitempty"`
	IconSeed    *string `json:"icon_seed,omitempty"`
}

UpdateListParams is the partial body for Contacts.UpdateList.

type UpdateTemplateParams 

type UpdateTemplateParams struct {
	Name       *string        `json:"name,omitempty"`
	Subject    *string        `json:"subject,omitempty"`
	HTML       *string        `json:"html_body,omitempty"`
	Text       *string        `json:"text_body,omitempty"`
	BlocksJSON map[string]any `json:"blocks_json,omitempty"`
}

UpdateTemplateParams is the partial body for Templates.Update.

type UpdateWebhookParams 

type UpdateWebhookParams struct {
	URL      *string  `json:"url,omitempty"`
	Events   []string `json:"events,omitempty"`
	IsActive *bool    `json:"is_active,omitempty"`
}

UpdateWebhookParams is the partial body for Webhooks.Update. IsActive maps to the wire field is_active.

type ValidationIssue 

type ValidationIssue struct {
	Field string `json:"field"`
	Error string `json:"error"`
}

ValidationIssue is a single reason a message would not send.

type ValidationResult 

type ValidationResult struct {
	Valid   bool              `json:"valid"`
	CanSend bool              `json:"can_send"`
	Issues  []ValidationIssue `json:"issues"`
	Plan    string            `json:"plan"`
	Usage   ValidationUsage   `json:"usage"`
}

ValidationResult is the result of Emails.Validate, a dry-run that never sends.

type ValidationUsage 

type ValidationUsage struct {
	Daily        int `json:"daily"`
	DailyLimit   int `json:"daily_limit"`
	Monthly      int `json:"monthly"`
	MonthlyLimit int `json:"monthly_limit"`
}

ValidationUsage is the sending-quota usage returned alongside a validation.

type Webhook 

type Webhook struct {
	ID        string   `json:"id"`
	URL       string   `json:"url"`
	Events    []string `json:"events"`
	Secret    string   `json:"secret"`
	IsActive  bool     `json:"is_active"`
	CreatedAt string   `json:"created_at"`
}

Webhook is a configured webhook endpoint. Secret is returned in plaintext.

type WebhookDelivery 

type WebhookDelivery struct {
	ID             string `json:"id"`
	WebhookID      string `json:"webhook_id"`
	EventType      string `json:"event_type,omitempty"`
	Status         string `json:"status"`
	ResponseStatus *int   `json:"response_status,omitempty"`
	Attempt        int    `json:"attempt"`
	NextRetryAt    string `json:"next_retry_at,omitempty"`
	CreatedAt      string `json:"created_at,omitempty"`
}

WebhookDelivery is a summary of one webhook delivery attempt.

type WebhookDeliveryDetail 

type WebhookDeliveryDetail struct {
	WebhookDelivery
	Payload      map[string]any `json:"payload"`
	ResponseBody string         `json:"response_body,omitempty"`
	EndpointURL  string         `json:"endpoint_url"`
}

WebhookDeliveryDetail is a delivery with the full payload and endpoint response.

type WebhookTestResult 

type WebhookTestResult struct {
	Queued bool   `json:"queued"`
	URL    string `json:"url"`
}

WebhookTestResult is the result of Webhooks.Test.

type Webhooks 

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

Webhooks is the webhooks resource, reached as client.Webhooks.

func (*Webhooks) Create 

func (w *Webhooks) Create(ctx context.Context, params CreateWebhookParams) (*Webhook, error)

Create creates a webhook. The signing secret is generated and returned.

func (*Webhooks) Delete 

func (w *Webhooks) Delete(ctx context.Context, id string) error

Delete deletes a webhook.

func (*Webhooks) GetDelivery 

func (w *Webhooks) GetDelivery(ctx context.Context, id, deliveryID string) (*WebhookDeliveryDetail, error)

GetDelivery fetches one delivery with its full payload and endpoint response.

func (*Webhooks) List 

func (w *Webhooks) List(ctx context.Context) ([]Webhook, error)

List returns your active webhooks.

func (*Webhooks) ListDeliveries 

func (w *Webhooks) ListDeliveries(ctx context.Context, id string, params ListDeliveriesParams) (*Page[WebhookDelivery], error)

ListDeliveries lists delivery attempts for a webhook as a paginated envelope.

func (*Webhooks) Test 

func (w *Webhooks) Test(ctx context.Context, id string) (*WebhookTestResult, error)

Test queues a sample email.delivered delivery to test the endpoint.

func (*Webhooks) Update 

func (w *Webhooks) Update(ctx context.Context, id string, params UpdateWebhookParams) (*Webhook, error)

Update updates a webhook's url, events, or active state (partial).

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.