Events API – Webhook
NewsmanSMTP can notify your application when one of these events happen:
- bounce – an email bounces back
- spam – somebody clicks report spam
- unsub – somebody unsubscribes
- reject – when we reject (refuse to send) one of your emails
- view – an email is opened (viewed)
- click – a link is clicked
The events are sent via POST to your webhook URL (@see settings page). Please use https (secure) URL for the webhook, for security reasons.
The events are batched up and sent as an array of events (one or more events can be sent in one request). The format of the event if quite easy. One parameter is sent via POST named newsman_events. The value of newsman_events is a JSON encoded string which is a LIST of events.
Each event is a hash map (dict) with following keys:
- id – the event id
- timestamp – integer timestamp (date of the event)
- type – event type (@see above available types)
- data – hash map (dict) with event related meta data
Here is an example of how to parse an event in PHP:
<?php print_r($_POST); /* Array ( [newsman_events] => [{"timestamp": 1382717823, "type": "reject", "id": "e24a6268-3d90-11e3-8080-808080808080", "data": {"send_id": "237aa4c2-5d42-11e6-b2f1-1dd49f2225ea", "meta": {"reason": "softbounce", "subject": "You have received a new message."}, "email": "new@email.todo"}}] ) */ $newsman_events = json_decode($_POST["newsman_events"], true); print_r($newsman_events[0]); /* Array ( [0] => Array ( [timestamp] => 1382717823 [type] => reject [id] => e24a6268-3d90-11e3-8080-808080808080 [data] => Array ( [send_id] => 237aa4c2-5d42-11e6-b2f1-1dd49f2225ea [meta] => Array ( [reason] => softbounce [subject] => You have received a new message. ) [email] => new@email.todo ) ) ) */ ?>
The data value will be a hash map (dict) with at least these 2 keys (email and meta). The meta is it’s self a hash map (dict) with event specific data.
Specific event meta keys are listed below by type.
- bounce – bounce_error_message, bounce_smtp_status, is_no_user_found, email_head
- spam – feedback_msg
- unsub – ip (optional), useragent (optional)
- reject – reason
- view – ip, subject, useragent, url (optional)
- click – ip, subject, useragent, url