API Documentation

You need to add parameter api_token=YOUR_API_TOKEN to each request to the API system
Example: https://app.hmailer.net/api/v1/lists?api_token=YOUR_API_TOKEN

Authentication

HTTP method	Endpoint	Function
Post	/api/v1/user/login	Get API token using email and password
	Parameters email User’s email password User’s password Returns API Token	Example: curl -X POST -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/user/login \ -d [email protected] \ -d password=yourpassword
Post	/api/v1/login-token	Generate one time login token
	Returns Token string	Example: curl -X POST -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/login-token \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48 User can login by visiting the following URL: https://app.hmailer.net/login/token/*|token_string|*

LISTS

HTTP method	Endpoint	Function
Post	/api/v1/lists	New list
	Parameters $name List’s name $from_email Default From email address $from_name Default From name divider Contact information $contact[company] Name $contact[state] State / Province / Region $contact[address_1] Address 1 $contact[address_2] Address 2 $contact[city] City $contact[zip] Zip / Postal code $contact[phone] Phone $contact[country_id] Country id $contact[email] Email $contact[url]   optional Home page $subscribe_confirmation Send subscription confirmation email (Double Opt-In) $send_welcome_email Send a final welcome email $unsubscribe_notification Send unsubscribe notification to subscribers $send_welcome_email Send a final welcome email Returns Creation messages in json	Example: curl -X POST -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/lists \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48 \ -d name=List+1 \ -d [email protected] \ -d from_name=ABC+Corp. \ -d contact[company]=ABC+Corp. \ -d contact[state]=Armagh \ -d contact[address_1]=14+Tottenham+Court+Road+London+England \ -d contact[address_2]=44-46+Morningside+Road+Edinburgh+Scotland+EH10+4BF \ -d contact[city]=Noname \ -d contact[zip]=80000 \ -d contact[phone]=123+456+889 \ -d contact[country_id]=1 \ -d contact[email][email protected] \ -d contact[url]=http://www.abccorp.org \ -d subscribe_confirmation=1 \ -d send_welcome_email=1 \ -d unsubscribe_notification=1
GET	/api/v1/lists	Get information about all lists
	Returns List of all user’s mail lists in json	Example: curl -X GET -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/lists \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
GET	/api/v1/lists/{uid}	Get information about a specific list
	Returns All list informations in json	Example: curl -X GET -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/lists/{uid} \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
Post	/api/v1/lists/{uid}/add-field	Add custom field to list
	Parameters $type Choose one of these types: text, number, datetime. $label Field’ label $tag The tag name may have alpha-numeric characters, as well as dashes and underscores. $default_value   optional Default value of the field Returns Creation messages in json	Example: curl -X POST -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/lists/{uid}/add-field \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48 \ -d type=text \ -d label=Custom \ -d tag=CUSTOM_FIELD_1 \ -d default_value=test
DELETE	/api/v1/lists/{uid}	Delete a list
	Parameters $uid List’s uid Returns Result messages in json	Example: curl -X DELETE -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/lists/{uid} \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48

CAMPAIGNS

HTTP method	Endpoint	Function
GET	/api/v1/campaigns	Get information about all campaigns
	Parameters $per_page   optional – default: 10 Number of subscribers per page $page Page number Returns List of all user’s campaigns in json	Example: curl -X GET -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/campaigns \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
Post	/api/v1/campaigns	Add new campaign
	Parameters $list_uid List’s uid $name New campaign name $subject Email subject $from_email From email $from_name From name $reply_to Reply-to email $track_open   optional – default: true Track open (true|false) $track_click   optional – default: true Track click (true|false) $sign_dkim   optional – default: true Sign dkim (true|false) $skip_failed_messages   optional – default: false Track open (true|false) $html   optional – default: false Campaign HTML content Returns New campaign’s information in json	Example: curl -X POST -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/campaigns \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48 \ -d mail_list_uid={list_uid} \ -d name=MyCampaign \ -d subject=HelloWorld \ -d [email protected] \ -d from_name=NoReply \ -d [email protected] \ -d track_open=true \ -d track_click=true \ -d sign_dkim=false \ -d skip_failed_messages=false \ -d html='<p>Hello!</p>'
GET	/api/v1/campaigns/{uid}	Get information about a specific campaign
	Returns Campaign’s information in json	Example: curl -X GET -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/campaigns/{uid} \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
PATCH	/api/v1/campaigns/{uid}	Update campaign
	Parameters $list_uid List’s uid $name Campaign name $subject Email subject $from_email From email $from_name From name $reply_to Reply-to email $track_open   optional – default: true Track open (true|false) $track_click   optional – default: true Track click (true|false) $sign_dkim   optional – default: true Sign dkim (true|false) $skip_failed_messages   optional – default: false Track open (true|false) Returns New campaign’s information in json	Example: curl -X PATCH -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/campaigns/{uid} \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48 \ -d name=MyCampaign2 \ -d subject=HelloWorld2 \ -d sign_dkim=true
Post	/api/v1/campaigns/{uid}/run	Run a specific campaign
	Returns Action messages in json	Example: curl -X POST -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/campaigns/{uid}/run \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
Post	/api/v1/campaigns/{uid}/pause	Pause a specific campaign
	Returns Action messages in json	Example: curl -X POST -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/campaigns/{uid}/pause \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
Post	/api/v1/campaigns/{uid}/resume	Resume a specific campaign
	Returns Action messages in json	Example: curl -X POST -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/campaigns/{uid}/resume \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
DELETE	/api/v1/campaigns/{uid}	Delete a campaign
	Parameters $uid Campaign’s uid Returns Result messages in json	Example: curl -X DELETE -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/campaigns/{uid} \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
GET	/api/v1/campaigns/{uid}/tracking-log/download	Download campaign tracking log
	Parameters $format Log format (default: CSV) Returns Campaign’s information in json	Example: curl -X GET -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/campaigns/{uid}/tracking-log/download \ -d type=csv \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
GET	/api/v1/campaigns/{uid}/open-log/download	Download campaign open log
	Parameters $format Log format (default: CSV) Returns Campaign’s information in json	Example: curl -X GET -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/campaigns/{uid}/open-log/download \ -d type=csv \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
GET	/api/v1/campaigns/{uid}/click-log/download	Download campaign click log
	Parameters $format Log format (default: CSV) Returns Campaign’s information in json	Example: curl -X GET -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/campaigns/{uid}/click-log/download \ -d type=csv \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
GET	/api/v1/campaigns/{uid}/bounce-log/download	Download campaign bounce log
	Parameters $format Log format (default: CSV) Returns Campaign’s information in json	Example: curl -X GET -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/campaigns/{uid}/bounce-log/download \ -d type=csv \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
GET	/api/v1/campaigns/{uid}/feedback-log/download	Download campaign feedback log
	Parameters $format Log format (default: CSV) Returns Campaign’s information in json	Example: curl -X GET -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/campaigns/{uid}/feedback-log/download \ -d type=csv \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
GET	/api/v1/campaigns/{uid}/unsubscribe-log/download	Download campaign unsubscribe log
	Parameters $format Log format (default: CSV) Returns Campaign’s information in json	Example: curl -X GET -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/campaigns/{uid}/unsubscribe-log/download \ -d type=csv \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48

SUBSCRIBERS

HTTP method	Endpoint	Function
GET	/api/v1/subscribers	Display list’s subscribers
	Parameters $list_uid List’s uid $open   optional – default: all yes – opened some campaigns no – not opened any campaign $click   optional – default: all yes – clicked some campaigns no – not clicked any campaign $per_page   optional – default: 25 Number of subscribers per page $page Page number Returns List of all list’s subscribers in json	Example: curl -X GET -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/subscribers \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48 \ -d list_uid={list_uid} \ -d per_page=20 \ -d page=1
Post	/api/v1/subscribers	Create subscriber for a mail list
	Parameters $list_uid List’s uid $EMAIL Subscriber’s email $tag   optional Subscriber’s tags, seperated by a comma (,). $status   optional Subscriber’s status: subscribed | unsubscribed | unconfirmed $[OTHER_FIELDS…]   optional All subscriber’s other fields: FIRST_NAME (?), LAST_NAME (?),… (depending on the list fields configuration) Returns Creation messages in json	Example: curl -X POST -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/subscribers \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48 \ -d list_uid={list_uid} \ -d [email protected] \ -d tag=foo,bar,tag+with+space, \ -d FIRST_NAME=Marine \ -d LAST_NAME=Joze \ -d status=subscribed
GET	/api/v1/subscribers/{id}	Get information about a specific subscriber
	Parameters $id Subsciber’s id or email Returns All subscriber information in json	Example: curl -X GET -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/subscribers/{id} \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
PATCH	/api/v1/subscribers/{id}	Update subscriber for a mail list
	Parameters $uid Subscriber’s uid $EMAIL Subscriber’s email $tag   optional Subscriber’s tags, seperated by a comma (,). $[OTHER_FIELDS…]   optional All subscriber’s other fields: FIRST_NAME (?), LAST_NAME (?),… (depending on the list fields configuration) Returns Update messages in json	Example: curl -X PATCH -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/subscribers/{id} \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48 \ -d [email protected] \ -d tag=foo,bar,tag+with+space, \ -d FIRST_NAME=Marine \ -d LAST_NAME=Joze \ -d status=unsubscribed
Post	/api/v1/subscribers/{id}/add-tag	Add tag(s) to subscriber
	Parameters $tag   optional Subscriber’s tags, seperated by a comma (,). Returns Creation messages in json	Example: curl -X POST -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/subscribers/-ID-/add-tag \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48 \ -d tag=foo,bar,tag+with+space
Post	/api/v1/subscribers/{id}/remove-tag	Remove tag(s) to subscriber
	Parameters $tag   optional Subscriber’s tags, seperated by a comma (,). Returns Update messages in json	Example: curl -X POST -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/subscribers/-ID-/remove-tag \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48 \ -d tag=foo,bar,tag+with+space
GET	/api/v1/subscribers/email/{email}	Find subscribers with email
	Parameters $email Subsciber’s email Returns All subscribers with the email	Example: curl -X GET -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/subscribers/email/{email} \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
PATCH	/api/v1/lists/{list_uid}/subscribers/{id}/subscribe	Subscribe a subscriber
	Parameters $list_uid List’s uid $id Subsciber’s id Returns Result messages in json	Example: curl -X PATCH -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/lists/{list_uid}/subscribers/{id}/subscribe \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
PATCH	/api/v1/lists/{list_uid}/subscribers/{id}/unsubscribe	Unsubscribe a subscriber
	Parameters $list_uid List’s uid $id Subsciber’s id Returns Result messages in json	Example: curl -X PATCH -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/lists/{list_uid}/subscribers/{id}/unsubscribe \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
PATCH	/api/v1/lists/{list_uid}/subscribers/email/{email}/unsubscribe	Unsubscribe a subscriber by email
	Parameters $list_uid List’s uid $email Subsciber’s email Returns Result messages in json	Example: curl -X PATCH -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/lists/{list_uid}/subscribers/email/{email}/unsubscribe \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48
DELETE	/api/v1/subscribers/{id}	Delete a subscriber
	Parameters $list_uid List’s uid $id Subsciber’s id Returns Result messages in json	Example: curl -X DELETE -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/subscribers/{id} \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48

Notification

HTTP method	Endpoint	Function
Post	/api/v1/notification/bounce	Send a HARD bounce to the application. Notice that it is not needed to inform the application of SOFT bounces
	Parameters $message_id Message’s id $description Notification message Returns Action messages in json	Example: curl -X POST -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/notification/bounce \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48 \ -d [email protected]

Feedback Loop

HTTP method	Endpoint	Function
Post	/api/v1/notification/feedback	Send a bounce or abuse report to the application. It could be a success / bounce / feedback or abuse report
	Parameters $message_id Message’s id $type Poassible values include: spam | abuse $description Notification message Returns Action messages in json	Example: curl -X POST -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/notification/feedback \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48 \ -d [email protected] \ -d type=abuse

FILE

HTTP method	Endpoint	Function
Post	/api/v1/file/upload	Upload file(s) to customer’s storage
	Parameters $file_url File url $subdirectory   optional – default: user root directory Custom subdirectory Returns Upload result message	Example: curl -X POST -H "accept:application/json" -G \ https://app.hmailer.net/api/v1/file/upload \ -d api_token=42whNNvAY27B1EkHQG02fLfUKtOOCCx9ijdnHIAznWjLQhZLIR54Uw5HWh48 \ -d files='[{"url":"http://example.com/images/logo_big.svg","subdirectory":"path/to/file"},{"url":"http://example.com/images/logo_big.svg","subdirectory":"path/to/file2"}]'