Documentation ¶
Overview ¶
Package srfax is a Go client library for interacting with the SRFax API service, supporting all POST operations. The official SRFax API docs can be found here:
https://www.srfax.com/developers/our-fax-api/
There are a few notable differences between the official API docs and this Go client:
1. As a result of variable types being returned in the Result field, see note about error handling: https://github.com/mfridman/srfax#a-note-about-error-handling
2. Response format supports JSON-only. Despite the API being able to return both XML and JSON, it is a design decision to support JSON only. As a result, sResponseFormat is not available as an optional parameter.
Index ¶
- func IDFromName(s string) (int, error)
- func PP(i interface{})
- type Client
- func (c *Client) CheckAuth() (bool, error)
- func (c *Client) CurrentMonthUsage(day int) (*Usage, error)
- func (c *Client) DeleteFax(ids []string, direction string) (*DeleteResp, error)
- func (c *Client) ForwardFax(cfg ForwardCfg, options ...ForwardOptions) (*ForwardResp, error)
- func (c *Client) GetFaxInbox(options ...InboxOptions) (*Inbox, error)
- func (c *Client) GetFaxOutbox(options ...OutboxOptions) (*Outbox, error)
- func (c *Client) GetFaxStatus(id int) (*FaxStatus, error)
- func (c *Client) GetFaxUsage(options ...FaxUsageOptions) (*FaxUsage, error)
- func (c *Client) GetMulFaxStatus(ids []string) (*MulFaxStatus, error)
- func (c *Client) QueueFax(files []File, cfg QueueCfg, options ...QueueOptions) (*QueueFaxResp, error)
- func (c *Client) RetrieveFax(ident, direction string, options ...RetrieveOptions) (*RetrieveResp, error)
- func (c *Client) StopFax(id int) (*StopFaxResp, error)
- func (c *Client) UpdateViewedStatus(cfg ViewedStatusCfg) (*ViewedStatus, error)
- type ClientCfg
- type DeleteResp
- type FaxStatus
- type FaxUsage
- type FaxUsageOptions
- type File
- type ForwardCfg
- type ForwardOptions
- type ForwardResp
- type Inbox
- type InboxOptions
- type MulFaxStatus
- type Outbox
- type OutboxOptions
- type QueueCfg
- type QueueFaxResp
- type QueueOptions
- type ResultError
- type RetrieveOptions
- type RetrieveResp
- type StopFaxResp
- type Usage
- type ViewedStatus
- type ViewedStatusCfg
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IDFromName ¶
IDFromName parses a filename string and returns the ID. File name format expected "20180101230101-8812-34_0|31524120", where the ID follows the pipe symbol.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is an SRFax client.
func (*Client) CheckAuth ¶
CheckAuth verifies client's ability to authenticate with SRFax. It is a wrapper around the GetFaxUsage method. Convenience method to quickly check if access ID & Pwd are valid.
func (*Client) CurrentMonthUsage ¶
CurrentMonthUsage reports the number of pages used by a specified account in the current period based on the account's reset day. To find your reset day navigate to https://www.srfax.com > My Account > Summary > look for "Your fax usage counter will reset on March 19, 2018". For this example the reset day would be 19.
func (*Client) DeleteFax ¶
func (c *Client) DeleteFax(ids []string, direction string) (*DeleteResp, error)
DeleteFax deletes one or more received or sent faxes for a given direction.
direction must be one of IN or OUT for inbound or outbound.
ids is a slice of fax identifiers to delete based on FaxFileName or FaxDetailsID. These are unique identifiers returned from a GetFaxOutbox or GetFaxInbox operation. Note, this method will take care of formatting ids accordingly, so it is safe to mix filenames with IDs: []string{"20170721124555-1213-4_0|272568938", "172568938"}
func (*Client) ForwardFax ¶
func (c *Client) ForwardFax(cfg ForwardCfg, options ...ForwardOptions) (*ForwardResp, error)
ForwardFax forwards a fax to other fax numbers.
func (*Client) GetFaxInbox ¶
func (c *Client) GetFaxInbox(options ...InboxOptions) (*Inbox, error)
GetFaxInbox retrieves a list of faxes received for a specified period of time.
func (*Client) GetFaxOutbox ¶
func (c *Client) GetFaxOutbox(options ...OutboxOptions) (*Outbox, error)
GetFaxOutbox retrieves a list of faxes sent for a specified period of time.
func (*Client) GetFaxStatus ¶
GetFaxStatus retrieves the status of a single sent fax. Works only with outbound faxes. Accepts a single id, i.e., FaxDetailsID, which is the result value from QueueFax or ForwardFax.
func (*Client) GetFaxUsage ¶
func (c *Client) GetFaxUsage(options ...FaxUsageOptions) (*FaxUsage, error)
GetFaxUsage reports usage for a specified user and period.
func (*Client) GetMulFaxStatus ¶
func (c *Client) GetMulFaxStatus(ids []string) (*MulFaxStatus, error)
GetMulFaxStatus retrieves status of multiple sent faxes. Works only with outbound faxes. Accepts a multiple id, i.e., FaxDetailsID, which is the result value from QueueFax or ForwardFax. Note, this method will take care of formatting ids accordingly with pipe(s).
func (*Client) QueueFax ¶
func (c *Client) QueueFax(files []File, cfg QueueCfg, options ...QueueOptions) (*QueueFaxResp, error)
QueueFax adds fax item(s) to a queue for delivery.
If Files is nil, the CoverPage option must be enabled. Otherwise will receive error: No Files to Fax
func (*Client) RetrieveFax ¶
func (c *Client) RetrieveFax(ident, direction string, options ...RetrieveOptions) (*RetrieveResp, error)
RetrieveFax returns a sent or received fax file in PDF or TIFF format.
ident will be either an sFaxDetailsID or sFaxFileName, returned from GetFaxInbox or GetFaxOutbox operation. Note, only one of sFaxDetailsID or sFaxFileName must be supplied.
If operation succeeds the Result value contains a base64-encoded string. The file format will be "PDF" or "TIF" – defaults to account settings if FaxFormat not supplied in optional args.
func (*Client) StopFax ¶
func (c *Client) StopFax(id int) (*StopFaxResp, error)
StopFax deletes a specified queued fax which has not yet been processed. FaxDetailsID returned from Queue_Fax
func (*Client) UpdateViewedStatus ¶
func (c *Client) UpdateViewedStatus(cfg ViewedStatusCfg) (*ViewedStatus, error)
UpdateViewedStatus marks an inbound or outbound fax as read or unread.
type ClientCfg ¶
ClientCfg specifies parameters required for establishing an SRFax client. Both ID and Pwd are unique to an SRFax account.
type DeleteResp ¶
DeleteResp is the response from a DeleteFax operation.
type FaxStatus ¶
type FaxStatus struct { Status string Result *struct { FileName string SentStatus string DateQueued string DateSent string ToFaxNumber string RemoteID string ErrorCode string AccountCode string Pages int EpochTime string Duration int Size int } }
FaxStatus represents the status of a single sent fax.
type FaxUsage ¶
type FaxUsage struct { Status string Result []struct { Period string ClientName string BillingNumber string UserID int SubUserID int NumberOfFaxes int NumberOfPages int } }
FaxUsage is the response from a GetFaxUsage operation.
type FaxUsageOptions ¶
type FaxUsageOptions struct { // ALL or RANGE – if not provided defaults to ALL Period string `json:"sPeriod,omitempty"` // Only required if RANGE is specified in sPeriod – date format must be YYYYMMDD StartDate string `json:"sStartDate,omitempty"` EndDate string `json:"sEndDate,omitempty"` // Set to Y to include faxes received by a sub user of the account as well IncludeSubUsers string `json:"sIncludeSubUsers,omitempty"` }
FaxUsageOptions specify optional arguments to modify fax usage report.
type File ¶
type File struct { // Valid File Name Name string // Base64 encoding of file contents Content string }
File represents a queueable fax item. It is the callers responsibility to ensure that Content is base64-encoded. Check the FAQs to see a list of supported file types: https://www.srfax.com/api-page/queue_fax/
type ForwardCfg ¶
type ForwardCfg struct { // Either FaxFileName or FaxDetailsID must be supplied // // FaxDetailsID of the fax – the ID is located after the "|" (pipe) character // of the FaxFileName FaxDetailsID string `json:"sFaxDetailsID,omitempty"` // FaxFileName returned from Get_Fax_Inbox or Get_Fax_Outbox FaxFileName string `json:"sFaxFileName,omitempty"` // IN or OUT for inbound or outbound Direction string `json:"sDirection"` // Sender fax number (must be 10 digits) CallerID int `json:"sCallerID"` // Sender email address SenderEmail string `json:"sSenderEmail"` // SINGLE when sending to one number; BROADCAST when sending to multiple numbers FaxType string `json:"sFaxType"` // Slice of string representing an 11 digit fax number ToFaxNumber []string `json:"-"` }
ForwardCfg specifies mandatory arguments when forwarding a fax.
type ForwardOptions ¶
type ForwardOptions struct { // The account number of a sub account, if you want to use a master account to // download a sub account’s fax SubUserID int `json:"sSubUserID,omitempty"` // Internal Reference Number (Maximum of 20 characters) AccountCode string `json:"sAccountCode,omitempty"` // Number of times the system is to retry a number if busy or an error is // encountered – number from 0 to 6 Retries int `json:"sRetries,omitempty"` // From: On the Fax Header Line(Maximum of 30 characters) FaxFromHeader string `json:"sFaxFromHeader,omitempty"` // Provide an absolute URL (beginning with http:// or https://) and the SRFax // system will POST back the fax status record when the fax completes. See docs // for more details: https://www.srfax.com/api-page/forward_fax/ NotifyURL string `json:"sNotifyURL,omitempty"` // The date you want to schedule a future fax for. // Must be in the format YYYY-MM-DD. Required if using QueueFaxTime QueueFaxDate string `json:"sQueueFaxDate,omitempty"` // The time you want to schedule a future fax for. Must be in the format HH:MM, // using 24 hour time (ie, 00:00 – 23:59). Required if using QueueFaxDate. // The timezone set on the account will be used when scheduling. QueueFaxTime string `json:"sQueueFaxTime,omitempty"` }
ForwardOptions specify optional arguments when forwarding a fax.
type ForwardResp ¶
ForwardResp represents information about a forwarded fax.
type Inbox ¶
type Inbox struct { Status string Result []struct { FileName string ReceiveStatus string Date string CallerID string RemoteID string ViewedStatus string UserID string UserFaxNumber string EpochTime int Pages int Size int } }
Inbox represents fax inbox information.
type InboxOptions ¶
type InboxOptions struct { // ALL or RANGE if not provided defaults to ALL Period string `json:"sPeriod,omitempty"` // Only required if RANGE is specified in sPeriod – date format must be YYYYMMDD StartDate string `json:"sStartDate,omitempty"` EndDate string `json:"sEndDate,omitempty"` // ALL – Show all faxes irrespective of Viewed Status (DEFAULT) // UNREAD – Only show faxes that have not been read // READ – Only show faxes that have been read ViewedStatus string `json:"sViewedStatus,omitempty"` // Set to Y to include faxes received by a sub user of the account as well IncludeSubUsers string `json:"sIncludeSubUsers,omitempty"` }
InboxOptions specify optional arguments when retrieving inbox items.
type MulFaxStatus ¶
type MulFaxStatus struct { Status string Result []struct { Pages string EpochTime string Duration string Size string FileName string SentStatus string DateQueued string DateSent string ToFaxNumber string RemoteID string ErrorCode string AccountCode string } }
MulFaxStatus represents the status of multiple sent faxes.
type Outbox ¶
type Outbox struct { Status string Result []struct { FileName string SentStatus string DateQueued string DateSent string EpochTime string ToFaxNumber string RemoteID string ErrorCode string AccountCode string Subject string UserID string UserFaxNumber string Pages int Duration int Size int } }
Outbox represents fax outbox information. More information can be found on the official docs: https://www.srfax.com/api-page/get_fax_outbox/, look for JSON Returned Variables.
type OutboxOptions ¶
type OutboxOptions struct { // ALL or RANGE if not provided defaults to ALL Period string `json:"sPeriod,omitempty"` // Only required if RANGE is specified in sPeriod – date format must be YYYYMMDD StartDate string `json:"sStartDate,omitempty"` EndDate string `json:"sEndDate,omitempty"` // Set to Y to include faxes received by a sub user of the account as well IncludeSubUsers string `json:"sIncludeSubUsers,omitempty"` }
OutboxOptions specify optional arguments when retrieving outbox items.
type QueueCfg ¶
type QueueCfg struct { // Sender fax number (must be 10 digits) CallerID int // Sender email address SenderEmail string // SINGLE when sending to one number; BROADCAST when sending to multiple numbers FaxType string // Slice of string representing an 11 digit fax number ToFaxNumber []string }
QueueCfg specify mandatory arguments when sending faxes.
If sending to a single number use SINGLE and pass in a slice of len 1. Otherwise use BROADCAST and pass in a slice of numbers (as string)
type QueueFaxResp ¶
QueueFaxResp represents information about faxes added to the queue.
type QueueOptions ¶
type QueueOptions struct { // Number of times the system is to retry a number if busy or // an error is encountered. Must be a number from 0 to 6 Retries int `json:"sRetries"` // Internal Reference Number (Maximum of 20 characters) AccountCode string `json:"sAccountCode"` // From: On the Fax Header Line(Maximum of 30 characters) FaxFromHeader string `json:"sFaxFromHeader"` // COVER PAGE OPTIONS // // To use one of the cover pages on file, specify the cover page you wish to use: // Basic, Standard, Company, or Personal CoverPage string `json:"sCoverPage"` // Sender name on the Cover Page CPFromName string `json:"sCPFromName"` // Recipient name on the Cover Page CPToName string `json:"sCPToName"` // Organiation on the Cover Page CPOrganization string `json:"sCPOrganization"` // Subject Line on the Cover Page // The subject line details are saved in the fax record even is a cover page is // not requested – so the subject can be used for filtering / searching CPSubject string `json:"sCPSubject"` // Comments placed in the body of the Cover Page CPComments string `json:"sCPComments"` // Provide an absolute URL (prefixed with http:// or https://) and the SRFax // system will POST back the fax status record when the fax completes. NotifyURL string `json:"sNotifyURL"` // The date you want to schedule a future fax for. // Must be in the format YYYY-MM-DD. Required if using QueueFaxTime QueueFaxDate string `json:"sQueueFaxDate"` // The time you want to schedule a future fax for. Must be in the format HH:MM, // using 24 hour time (ie, 00:00 – 23:59). Required if using QueueFaxDate. // The timezone set on the account will be used when scheduling. QueueFaxTime string `json:"sQueueFaxTime"` }
QueueOptions specify optional arguments when sending faxes.
If the default cover page on the account is set to "Attachments ONLY" the cover page will not be created irrespective of the CoverPage variable. If CoverPage is not provided all cover page variables are ignored For more info see docs: https://www.srfax.com/api-page/queue_fax/
json tag used for reflection.
type ResultError ¶
type ResultError struct { Status string // Status value from Failed Response Raw string // Unformatted Result error message from Failed Response }
ResultError represents an error when Result returns Failed. Caller can access the Status and Raw (Result error message) fields.
func (*ResultError) Error ¶
func (r *ResultError) Error() string
type RetrieveOptions ¶
type RetrieveOptions struct { // The account number of a sub account, // if you want to use a master account to download a sub account’s fax SubUserID string `json:"sSubUserID,omitempty"` // PDF or TIFF, defaults to account settings if not supplied FaxFormat string `json:"sFaxFormat,omitempty"` // Y mark fax as viewed once method completes successfully. // N leave viewed status as is (default) MarkAsViewed string `json:"sMarkasViewed,omitempty"` }
RetrieveOptions specify optional arguments when retriving faxes.
type RetrieveResp ¶
type RetrieveResp struct { Status string // If successful the Result field will contain Base64 encoded fax file contents Result string }
RetrieveResp is the response from retrieving a fax.
func (*RetrieveResp) DecodeResult ¶
func (r *RetrieveResp) DecodeResult() ([]byte, error)
DecodeResult decodes a base64-encoded Result string and returns the raw bytes.
type StopFaxResp ¶
StopFaxResp is the response from a StopFax operation.
type ViewedStatus ¶
ViewedStatus is the response from a UpdateViewedStatus operation.
type ViewedStatusCfg ¶
type ViewedStatusCfg struct { // Either the FaxFileName or the FaxDetailsID must be supplied // // When passing FaxFileName, the entire name (including pipe and ID) // must be supplied. E.g., 20170101230101-1212-21_7|12124720 FaxDetailsID int `json:"sFaxDetailsID,omitempty"` FaxFileName string `json:"sFaxFileName,omitempty"` // IN or OUT for inbound or outbound fax Direction string `json:"sDirection"` // Y marks fax READ, N marks fax UNREAD MarkAsViewed string `json:"sMarkasViewed"` }
ViewedStatusCfg specifies mandatory arguments when updating the Viewed status of a fax.