mail

type Account ¶

type Account struct {
	ClientID          string `json:"client_id"`
	EmailAddr         string `json:"emailaddr"`
	Label             string `json:"label"`
	Username          string `json:"username"`
	Autoresponder     string `json:"autoresponder"`
	AutoresponderText string `json:"autoresponder_text"`
	Active            string `json:"active"`
	Quota             string `json:"quota"`
	SpamStrategy      string `json:"spam_strategy"`
	QuotaUsed         string `json:"quota_used,omitempty"`
	QuotaPercent      string `json:"quota_percent,omitempty"`
	MessageCount      string `json:"message_count,omitempty"`
	LastUpdated       string `json:"last_updated,omitempty"`
	Key               string `json:"key,omitempty"`
	DateAdded         string `json:"date_added,omitempty"`
}

Account is a mail account record. Field availability varies by the source endpoint:

• search_accounts populates the first 9 fields only.
• list_accounts adds QuotaUsed, QuotaPercent, MessageCount, LastUpdated.
• get_account additionally populates Key and DateAdded.

Fields not populated by an endpoint deserialise to their zero value (empty string for the string-typed fields). All numeric / boolean values are returned as strings by the API ("0", "1", "yes", "no") and represented as Go strings here for fidelity.

type AccountParams ¶

type AccountParams struct {
	Password          string `url:"params[password],omitempty"`
	Label             string `url:"params[label],omitempty"`
	Username          string `url:"params[username],omitempty"`
	Autoresponder     string `url:"params[autoresponder],omitempty"`
	AutoresponderText string `url:"params[autoresponder_text],omitempty"`
	SpamStrategy      string `url:"params[spam_strategy],omitempty"`
	Quota             string `url:"params[quota],omitempty"`
}

AccountParams holds the optional per-account settings shared by AddAccount and UpdateAccount. For AddAccount the Password field is required.

type AddAccountOptions ¶

type AddAccountOptions struct {
	ServerOptions
	Email string `url:"email"`
	AccountParams
}

AddAccountOptions describes a new mail account to create. ServerName, Email, and Password are required; the rest are optional. (AccountParams is embedded anonymously so its url:"params[...]" tags are picked up by go-querystring.)

type AddAliasDomainOptions ¶

type AddAliasDomainOptions struct {
	ServerOptions
	AliasDomain  string `url:"alias_domain"`
	ParentDomain string `url:"parent_domain"`
}

AddAliasDomainOptions adds an alias-domain mapping (one domain pointing at another for mail purposes).

type AddAliasOptions ¶

type AddAliasOptions = AliasMapping

AddAliasOptions adds an alias mapping.

type AddDomainOptions ¶

type AddDomainOptions struct {
	ServerOptions
	Domain string `url:"domain"`
}

AddDomainOptions describes a domain to add to the mail server.

Domain is validated against a TLD allowlist server-side. RFC 2606 reserved test TLDs (.example, .test, .localhost, .invalid) are rejected with "Please specify a valid domain name." Use a domain on a real public-suffix TLD, or one of SiteHost's wildcard test domains (sth.nz) for SDK testing.

type AddForwardOptions ¶

type AddForwardOptions = AliasMapping

AddForwardOptions adds a forwarder mapping.

type Alias ¶

type Alias struct {
	ClientID    string `json:"client_id,omitempty"`
	Source      string `json:"source"`
	Destination string `json:"destination"`
}

Alias is a mail alias mapping (one address redirecting to another). Aliases are the same data shape as forwards (source → destination); the type names exist to mirror the API's separate endpoints.

ClientID is populated by search_aliases but not by list_aliases.

type AliasMapping ¶

type AliasMapping struct {
	ServerOptions
	Source      string `url:"source"`
	Destination string `url:"destination"`
}

AliasMapping is the source→destination pair used by add/ delete operations for both aliases and forwarders. Note the delete operations require both fields — the API rejects calls with only the source.

type Client ¶

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

Client is a Service to work with the SiteHost Mail API. defaultServerName, when non-empty, is used as the server_name for any operation whose request didn't provide one — see NewForServer.

func New(c *api.Client) *Client

func NewForServer(c *api.Client, serverName string) *Client

func (s *Client) AddAccount(ctx context.Context, opt AddAccountOptions) (response JobResponse, err error)

func (s *Client) AddAlias(ctx context.Context, opt AddAliasOptions) (response JobResponse, err error)

func (s *Client) AddAliasDomain(ctx context.Context, opt AddAliasDomainOptions) (response models.APIResponse, err error)

func (s *Client) AddDomain(ctx context.Context, opt AddDomainOptions) (response models.APIResponse, err error)

func (s *Client) AddForward(ctx context.Context, opt AddForwardOptions) (response JobResponse, err error)

func (s *Client) DeleteAccount(ctx context.Context, opt DeleteAccountOptions) (response JobResponse, err error)

func (s *Client) DeleteAlias(ctx context.Context, opt DeleteAliasOptions) (response models.APIResponse, err error)

func (s *Client) DeleteAliasDomain(ctx context.Context, opt DeleteAliasDomainOptions) (response models.APIResponse, err error)

func (s *Client) DeleteDomain(ctx context.Context, opt DeleteDomainOptions) (response models.APIResponse, err error)

func (s *Client) DeleteForward(ctx context.Context, opt DeleteForwardOptions) (response models.APIResponse, err error)

func (s *Client) GetAccount(ctx context.Context, opt GetAccountOptions) (response GetAccountResponse, err error)

func (s *Client) GetServerInfo(ctx context.Context, opt GetServerInfoOptions) (response GetServerInfoResponse, err error)

func (s *Client) ListAccounts(ctx context.Context, opt ListAccountsOptions) (response ListAccountsResponse, err error)

func (s *Client) ListAliases(ctx context.Context, opt ListAliasesOptions) (response ListAliasesResponse, err error)

func (s *Client) ListAll(ctx context.Context, opt ListAllOptions) (response ListAllResponse, err error)

type=0  mailbox      Username + EmailAddr + Label
type=1  alias        EmailAddr + Destination
type=2  forward      EmailAddr + Destination

func (s *Client) ListDomains(ctx context.Context, opt ListDomainsOptions) (response ListDomainsResponse, err error)

func (s *Client) ListForwards(ctx context.Context, opt ListForwardsOptions) (response ListForwardsResponse, err error)

func (s *Client) SearchAccounts(ctx context.Context, opt SearchAccountsOptions) (response SearchAccountsResponse, err error)

func (s *Client) SearchAliases(ctx context.Context, opt SearchAliasesOptions) (response SearchAliasesResponse, err error)

func (s *Client) SearchForwards(ctx context.Context, opt SearchForwardsOptions) (response SearchForwardsResponse, err error)

func (s *Client) UpdateAccount(ctx context.Context, opt UpdateAccountOptions) (response JobResponse, err error)

func (s *Client) UpdateDomain(ctx context.Context, opt UpdateDomainOptions) (response models.APIResponse, err error)

type DeleteAccountOptions ¶

type DeleteAccountOptions struct {
	ServerOptions
	Email string `url:"email"`
}

DeleteAccountOptions identifies the account to delete.

type DeleteAliasDomainOptions ¶

type DeleteAliasDomainOptions struct {
	ServerOptions
	AliasDomain string `url:"alias_domain"`
}

DeleteAliasDomainOptions removes an alias-domain mapping.

type DeleteAliasOptions ¶

type DeleteAliasOptions = AliasMapping

DeleteAliasOptions deletes an alias mapping.

type DeleteDomainOptions ¶

type DeleteDomainOptions struct {
	ServerOptions
	Domain string `url:"domain"`
}

DeleteDomainOptions identifies the domain to remove.

type DeleteForwardOptions ¶

type DeleteForwardOptions = AliasMapping

DeleteForwardOptions deletes a forwarder mapping.

type Domain ¶

type Domain struct {
	ClientID     string `json:"client_id"`
	Domain       string `json:"domain"`
	ParentDomain string `json:"parent_domain"`
	CatchAll     string `json:"catch_all"`
	State        string `json:"state"`
	Accounts     int    `json:"accounts"`
	Nicknames    int    `json:"nicknames"`
	Forwarders   int    `json:"forwarders"`
	TotalUsed    int    `json:"total_used"`
}

Domain is a single mail-domain entry from list_domains. State is returned as a string ("1" enabled / "0" disabled). ParentDomain is non-empty for alias domains pointing at another domain; otherwise empty. Accounts / Nicknames / Forwarders / TotalUsed are returned as JSON numbers (so int in Go), distinct from the string-typed counters elsewhere in the API.

type DomainParams ¶

type DomainParams struct {
	Catchall string `url:"params[catchall],omitempty"`
	State    string `url:"params[state],omitempty"`
}

DomainParams holds the optional per-domain settings for UpdateDomain.

type EmailRecord ¶

type EmailRecord struct {
	Type        int    `json:"type"`
	Username    string `json:"username,omitempty"`
	EmailAddr   string `json:"emailaddr"`
	Label       string `json:"label,omitempty"`
	Destination string `json:"destination,omitempty"`
}

EmailRecord is a single row from /mail/list_all.json — the union of mailboxes, aliases, and forwarders. Type distinguishes the kind:

0  mailbox      Username + EmailAddr + Label populated
1  forward      EmailAddr + Destination populated
2  alias        EmailAddr + Destination populated

Fields not relevant to a row's Type deserialise to empty.

type Forward ¶

type Forward struct {
	ClientID    string `json:"client_id,omitempty"`
	Source      string `json:"source"`
	Destination string `json:"destination"`
}

Forward is a mail forwarder mapping (a source address forwarding to a destination, typically external).

ClientID is populated by search_forwards but not by list_forwards.

type GetAccountOptions ¶

type GetAccountOptions struct {
	ServerOptions
	Email string `url:"email"`
}

GetAccountOptions identifies the mail server and the email address whose account to fetch.

type GetAccountResponse ¶

type GetAccountResponse struct {
	Return Account `json:"return"`
	models.APIResponse
}

GetAccountResponse represents the response from get_account.

type GetServerInfoOptions ¶

type GetServerInfoOptions struct {
	ServerOptions
}

GetServerInfoOptions identifies the mail server to fetch info about.

type GetServerInfoResponse ¶

type GetServerInfoResponse struct {
	Return ServerInfo `json:"return"`
	models.APIResponse
}

GetServerInfoResponse represents the response from get_server_info.

type JobResponse ¶

type JobResponse struct {
	Return struct {
		models.Job `json:"job"`
	} `json:"return"`
	models.APIResponse
}

JobResponse is the response shape for the mail write operations that queue an asynchronous job: AddAccount, UpdateAccount, DeleteAccount, AddAlias, AddForward. The returned job ID is for tracking only.

The other write operations (AddDomain, UpdateDomain, DeleteDomain, DeleteAlias, DeleteForward, AddAliasDomain, DeleteAliasDomain) take effect synchronously and return only models.APIResponse.

type ListAccountsOptions ¶

type ListAccountsOptions struct {
	ServerOptions
	Domain    string `url:"domain"`
	EmailAddr string `url:"filters[emailaddr],omitempty"`
}

ListAccountsOptions identifies the mail server and domain whose accounts to list. EmailAddr is an optional filter restricting results to a specific address.

type ListAccountsResponse ¶

type ListAccountsResponse struct {
	Return []Account `json:"return"`
	models.APIResponse
}

ListAccountsResponse represents the response from list_accounts.

type ListAliasesOptions ¶

type ListAliasesOptions struct {
	ServerOptions
	Domain string `url:"domain"`
	Source string `url:"filters[source],omitempty"`
}

ListAliasesOptions identifies the mail server and domain whose aliases to list. Source is an optional filter restricting results to a specific source address.

type ListAliasesResponse ¶

type ListAliasesResponse struct {
	Return []Alias `json:"return"`
	models.APIResponse
}

ListAliasesResponse represents the response from list_aliases.

type ListAllOptions ¶

type ListAllOptions struct {
	ServerOptions
	Domain string `url:"domain"`
}

ListAllOptions identifies the mail server and domain whose every-email-record listing to fetch (mailboxes + aliases + forwarders, in a single union view).

type ListAllResponse ¶

type ListAllResponse struct {
	Return []EmailRecord `json:"return"`
	models.APIResponse
}

ListAllResponse is the return from /mail/list_all.json.

type ListDomainsOptions ¶

type ListDomainsOptions struct {
	ServerOptions
}

ListDomainsOptions identifies the mail server whose domains to list.

type ListDomainsResponse ¶

type ListDomainsResponse struct {
	Return []Domain `json:"return"`
	models.APIResponse
}

ListDomainsResponse represents the response from list_domains.

type ListForwardsOptions ¶

type ListForwardsOptions struct {
	ServerOptions
	Domain string `url:"domain"`
	Source string `url:"filters[source],omitempty"`
}

ListForwardsOptions identifies the mail server and domain whose forwarders to list. Source is an optional filter restricting results to a specific source address.

type ListForwardsResponse ¶

type ListForwardsResponse struct {
	Return []Forward `json:"return"`
	models.APIResponse
}

ListForwardsResponse represents the response from list_forwards.

type SearchAccountsOptions ¶

type SearchAccountsOptions struct {
	ServerOptions
	EmailAddr string `url:"query[emailaddr],omitempty"`
	Username  string `url:"query[username],omitempty"`
	Active    string `url:"query[active],omitempty"`
	Quota     string `url:"query[quota],omitempty"`
	Offset    int    `url:"offsets[offset],omitempty"`
	Limit     int    `url:"offsets[limit],omitempty"`
}

SearchAccountsOptions identifies the mail server to search against. At least one of EmailAddr / Username / Active / Quota should be set; the API rejects calls with no query[*] filter.

type SearchAccountsResponse ¶

type SearchAccountsResponse struct {
	Return []Account `json:"return"`
	models.APIResponse
}

SearchAccountsResponse represents the response from search_accounts.

type SearchAliasesOptions ¶

type SearchAliasesOptions struct {
	ServerOptions
	Source      string `url:"query[source],omitempty"`
	Destination string `url:"query[destination],omitempty"`
	Offset      int    `url:"offsets[offset],omitempty"`
	Limit       int    `url:"offsets[limit],omitempty"`
}

SearchAliasesOptions identifies the mail server to search against for aliases. At least one of Source or Destination must be set; the API rejects calls with no query[*] filter.

type SearchAliasesResponse ¶

type SearchAliasesResponse struct {
	Return []Alias `json:"return"`
	models.APIResponse
}

SearchAliasesResponse represents the response from search_aliases.

type SearchForwardsOptions ¶

type SearchForwardsOptions struct {
	ServerOptions
	Source      string `url:"query[source],omitempty"`
	Destination string `url:"query[destination],omitempty"`
	Offset      int    `url:"offsets[offset],omitempty"`
	Limit       int    `url:"offsets[limit],omitempty"`
}

SearchForwardsOptions identifies the mail server to search against for forwarders. At least one of Source or Destination must be set.

type SearchForwardsResponse ¶

type SearchForwardsResponse struct {
	Return []Forward `json:"return"`
	models.APIResponse
}

SearchForwardsResponse represents the response from search_forwards.

type ServerInfo ¶

type ServerInfo struct {
	Hostname    string `json:"hostname"`
	WebmailURL  string `json:"webmail_url"`
	DateAdded   string `json:"date_added"`
	DateUpdated string `json:"date_updated"`
}

ServerInfo describes a mail server's connection details.

type ServerOptions ¶

type ServerOptions struct {
	ServerName string `url:"server_name"`
}

ServerOptions identifies a mail server (the API's server_name parameter). Embedded into operation-specific option structs. Leave ServerName empty to inherit from a NewForServer-captured default; otherwise it is required.

type UpdateAccountOptions ¶

type UpdateAccountOptions struct {
	ServerOptions
	Email string `url:"email"`
	AccountParams
}

UpdateAccountOptions describes an account update. All AccountParams fields are optional; supplying none is a no-op.

type UpdateDomainOptions ¶

type UpdateDomainOptions struct {
	ServerOptions
	Domain string `url:"domain"`
	DomainParams
}

UpdateDomainOptions describes a domain update.