sharklaser

package module
v0.0.0-...-a9a74a5 Latest Latest
Warning

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

 Go to latest Published: Mar 24, 2018 License: GPL-3.0 Imports: 12 Imported by: 1

README

Sharklaser is a golang library for interfacing with the Guerrilla Mail disposable e-mail service API. It is named after one of Guerrilla Mail's most memorable domain names.

Obtaining it

Once you've set up go, this should do it:

go get -u gitlab.com/lonvale/sharklaser

Using it

Usage is centred around the Sharklaser type:

shark := sharklaser.New() // Initialise.
getaddr_err := shark.SLGetAddr() // Obtain a disposable address (accessible at shark.EmailAddr).
getmail_err := shark.SLUpdate() // Check for e-mail (saved to shark.Emails)
mail_body, fetch_err := shark.SLFetchEmail(0) // Retrieve body for e-mail at index 0.
shark.ForgetMe() // Discard address.

For a usage example, the brave-hearted can try to make sense of our very own grrla text-mode client.

API is not to be considered stable at this point. Changes in function signatures and whatnot are likely in the next stages of development. Exercise caution.

License

Sharklaser is Free Software made available under the terms of the GNU General Public License, version 3 or later.

Documentation

Overview

Package sharklaser provides an interface to the Guerrilla Mail API. Client applications can use it to obtain temporary email addresses and receive emails. Its name is a reference to a domain name famously owned by Guerrilla Mail.

API specification can be found here: https://www.guerrillamail.com/GuerrillaMailAPI.html.

Sharklaser{} exports methods for each API function as well as higher-level wrapper methods (whose name begins with SL) for some. Direct API methods do almost no housekeeping and return rather bare representations of response data, whereas SL* methods simply return error values and try to do the sensible thing with the returned data (e.g. storing received email address in Sharklaser.Email and watching for expiration, saving emails to Sharklaser.Emails). It is needless to say which set client applications are encouraged to use.

Rather poor usage example:

Create new Sharklaser object: 

shark := sharklaser.New()

Fill in any properties you don't like the default values for: 

shark.UserAgent = "SuperFancyClient -=iCeCoLdMoD=-"
shark.UpdateInt = 120
shark.DomainName = "sharklasers.com"

Get a temporary address, check for email: 

getaddr_err := shark.SLGetAddr() // Fills in shark.EmailAddr, notices address expiration
getmail_err := shark.SLUpdate() // Saves them to shark.Emails and updates next update time

Access Sharklaser.Emails: 

fmt.Println(shark.Emails[0].Mail_subject)

Retrieve email body: 

mail_body, fetch_err := shark.SLFetchEmail(0) // Fetches email body if unread, subsequently retrieves it from memory.

Be polite and let the server release the address when you're done: 

shark.ForgetMe()

If WriteDebugLog is set to true and DebugLogFname contains a valid filename, API requests and responses will be logged to that file.

If DummyMode is set to true, no network requests will be sent. Instead, a file in directory DummyDir whose name matches the API function requested will be read. This is useful if you're developing a client application and do not wish to bother Guerrilla Mail with constant requests. However, parameters will be stripped and so only basic API interaction can be emulated this way.

Index

Constants

View Source 
const (
	APIURL               = "https://api.guerrillamail.com/ajax.php"
	EMAIL_TTL            = int64(3600)
	EMAIL_LIST_MAX       = 20
	HEADER_UA            = "User-Agent"
	HEADER_COOKIE        = "Cookie"
	HEADER_SETCOOKIE     = "Set-Cookie"
	HEADER_CONTENTTYPE   = "Content-Type"
	CONTENTTYPE_POST     = "application/x-www-form-urlencoded"
	PATTERN_SUBS_DELETED = "SUBSCR=deleted"
)
View Source 
const (
	ERROR_PREFIX = "SRKLSR: "
	// get_email_list with offset <1 fetches the automated welcome message,
	// which uses an incompatible version of the API.
	// Better to refuse to fetch it.
	ERROR_EXPIRED       = ERROR_PREFIX + "email address expired"
	ERROR_GETEMAILSEQ   = ERROR_PREFIX + "get_email_list with offset <1 not supported"
	ERROR_MAILNOTINLIST = ERROR_PREFIX + "email ID not found in local list"
	ERROR_EMPTYVALUE    = ERROR_PREFIX + "received an empty value"
	ERROR_FORGETFAILED  = ERROR_PREFIX + "failed to discard address"
)

Error message constants.

View Source 
const (
	FUNCTION_GETEMAIL   = "get_email_address"
	FUNCTION_SETEMAIL   = "set_email_user"
	FUNCTION_CHECKEMAIL = "check_email"
	FUNCTION_GETLIST    = "get_email_list"
	FUNCTION_GETOLDER   = "get_older_list"
	FUNCTION_FETCHEMAIL = "fetch_email"
	FUNCTION_FORGETME   = "forget_me"
	FUNCTION_DELEMAIL   = "del_email"
	PARAM_FUNCTION      = "f"
	PARAM_IP            = "ip"
	PARAM_AGENT         = "agent"
	PARAM_LANG          = "lang"
	PARAM_SUBSCR        = "SUBSCR"
	PARAM_EMAILUSER     = "email_user"
	PARAM_SEQ           = "seq"
	PARAM_OFFSET        = "offset"
	PARAM_EMAILID       = "email_id"
	PARAM_EMAILADDR     = "email_addr"
	PARAM_EMAILIDS      = "email_ids[]"
	LABEL_SESSIONCOOKIE = "PHPSESSID"
	LABEL_SUBSCOOKIE    = PARAM_SUBSCR
)

Guerillamail API-related constants.

Variables

View Source 
var DomainNames = [...]string{"sharklasers.com", "guerrillamail.info", "grr.la", "guerrillamail.biz", "guerrillamail.com", "guerrillamail.de", "guerrillamail.net", "guerrillamail.org", "guerrillamailblock.com", "pokemail.net", "spam4.me"}

List of valid Guerrilla Mail domain names.

Functions

This section is empty.

Types

type APIResponse 

type APIResponse struct {
	Email_addr      string
	Email_timestamp int64  // Email address creation time.
	Alias           string // Obfuscated address.
	Sid_token       string // This contains a copy of the PHPSESSID cookie.
	Deleted_ids     []string
	// Subscription stuff:
	S_active       string // Y or N.
	S_date         string
	S_time         int64
	S_time_expires int64
}

All the top-level parameters a response from the API should consist of.

type Email 

type Email struct {
	Mail_id        string
	Mail_from      string
	Mail_subject   string // Unescaped by us.
	Mail_excerpt   string // Unescaped by us.
	Mail_timestamp string
	Mail_read      string // 0 or 1.
	Mail_date      string
	Att            string
	Mail_size      string
	Mail_body      string // Unescaped by us (but see note at FetchEmail()).
	// Parameters not in API, added by us:
	FlaggedForDeletion bool
}

Parameters for each email in a list as provided in reply to check_email.

type EmailList 

type EmailList struct {
	List      []Email
	Count     string
	Email     string // Watch this variable for changes.
	Alias     string
	Ts        int64 // Email address creation time.
	Sid_token string
}

Reply to check_email or get_email_list.

type Sharklaser 

type Sharklaser struct {

	// User-settable preferences.
	UserAgent  string
	UpdateInt  int64
	DomainName string
	// Received from API, or filled in based on API responses.
	CreationTS   int64
	SessionToken string
	SubsToken    string // This is both user- and API-set.
	SubsActive   bool   // Not used.
	EmailAddr    string
	Alias        string
	LatestEmail  int
	AddrActive   bool
	// Expired      bool // Merged with AddrActive.
	// LatestUpdate int64
	NextUpdate int64
	Emails     []Email
	// Debug log: dump raw requests and responses to a file.
	WriteDebugLog bool
	DebugLogFname string
	// Dummy mode: no network interaction, read responses from files.
	DummyMode bool
	DummyDir  string
	// contains filtered or unexported fields
}

Central point of the sharklaser library.

func New 

func New() *Sharklaser

New sets up a new Sharklaser object and returns a pointer to it.

func (*Sharklaser) CheckEmail 

func (shark *Sharklaser) CheckEmail(seq int) (emaillist *EmailList, err error)

CheckEmail requests the list of emails starting at sequence number seq. Since the API for it is buggy and GetEmailList basically does the same thing, it is recommended to use that other method instead.

func (*Sharklaser) DelEmail 

func (shark *Sharklaser) DelEmail(email_ids []string) (deleted_ids []string, err error)

DelEmail deletes a list of emails from the server.

func (*Sharklaser) FetchEmail 

func (shark *Sharklaser) FetchEmail(emailid string) (email *Email, err error)

FetchEmail downloads an email and returns its unescaped body. Mail_body is missing from get_email_list replies but present in fetch_email replies. FetchEmail() therefore constructs a new Email object intependent of any that may exist in Sharklaser.Emails, and simply returns its unescaped Mail_body.

func (*Sharklaser) ForgetMe 

func (shark *Sharklaser) ForgetMe() (success bool, err error)

ForgetMe requests that the server forget the current email address.

func (*Sharklaser) GetEmailAddress 

func (shark *Sharklaser) GetEmailAddress() (apiresp *APIResponse, err error)

GetEmail requests a new email address.

func (*Sharklaser) GetEmailList 

func (shark *Sharklaser) GetEmailList(offset, seq int) (emaillist *EmailList, err error)

GetEmailList requests the list of emails starting at sequence number seq. To avoid fetching the automated welcome message, which breaks the API, we disallow an offset lesser than 1.

func (*Sharklaser) ReckonTimeLeft 

func (shark *Sharklaser) ReckonTimeLeft() int64

ReckonTimeLeft calculates time left before account expires based on creation timestamp and current time.

func (*Sharklaser) SLDelEmail 

func (shark *Sharklaser) SLDelEmail() (err error)

SLDelEmail is a wrapper around Sharklaser.DelEmail(). It takes care of deleting from the local email list the messages that the API reports as successfully deleted.

func (*Sharklaser) SLExtend 

func (shark *Sharklaser) SLExtend() (err error)

SLExtend requests an extension of the address' lifetime. The extend API function is disabled, so this is actually a wrapper around Sharklaser.SetEmailUser() instead.

func (*Sharklaser) SLFetchEmail 

func (shark *Sharklaser) SLFetchEmail(index int) (body string, err error)

SLFetchEmail is a wrapper around Sharlaser.FetchEmail(). It takes care of requesting and storing an email's body only if it hasn't been already retrieved.

func (*Sharklaser) SLForgetMe 

func (shark *Sharklaser) SLForgetMe() (err error)

SLForgetMe is a wrapper around Sharklaser.ForgetMe().

func (*Sharklaser) SLGetAddr 

func (shark *Sharklaser) SLGetAddr() (err error)

SLGetAddr is a wrapper around Sharklaser.GetEmailaddress().

func (*Sharklaser) SLRenew 

func (shark *Sharklaser) SLRenew() (err error)

SLRenew initiates a new session by requesting a new address and then promptly switches to the previous address, in practise extending an address' lifetime beyond its expiration.

func (*Sharklaser) SLSetUser 

func (shark *Sharklaser) SLSetUser(user string) (err error)

SLSetUser is a wrapper around Sharklaser.SetEmailUser().

func (*Sharklaser) SLUpdate 

func (shark *Sharklaser) SLUpdate() (err error)

SLUpdate is a wrapper around Sharklaser.GetEmaillist(). It takes care of requesting only new emails, saving them in Sharklaser.Emails and calculating the time when the next automatic update is due.

func (*Sharklaser) SetEmailUser 

func (shark *Sharklaser) SetEmailUser(user string) (apiresp *APIResponse, err error)

SetEmail requests setting a specific email username.

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.