Skip to main content

Email Webhooks

Email webhooks are a mechanism that allows the client to receive real-time events related to transactional Emails sent through the Arpoone API.

The URLs configured by the client will be invoked by the Arpoone server (HTTP POST), sending information in JSON format.

Configuration​

The transactional Email operation allows for the configuration of 5 webhooks, representing 5 events related to the email:

  • Bounced;
  • Clicked;
  • Opened;
  • Spam;
  • Unsubscribed.

This configuration is made in the emailWebhooks property of the payload, used in the transactional Email endpoint, where the client can choose which events they want to be notified about (using the enabled property (bool)).

Each endpoint configured by the client in the request can be assigned to a different event related to the email they sent. Example of configuration (inside the transactional Email payload):

...
"emailWebhooks": {
    "bounced": {
        "url":"https://your-endpoint-here.com/bounced",
        "enabled": true
    },
    "clicked": {
        "url":"https://your-endpoint-here.com/clicked",
        "enabled": true
    },
    "opened": {
        "url":"https://your-endpoint-here.com/opened",
        "enabled": true
    },
    "spam": {
        "url":"https://your-endpoint-here.com/spam",
        "enabled": true
    },
    "unsubscribed": {
        "url":"https://your-endpoint-here.com/unsub",
        "enabled": true
    }
}
...

Invocation​

The structure of the Email webhooks that Arpoone will send to each of the endpoints indicated by the client is as follows:

application/json
[
  {
    "EventType": <string>,
    "Email": <string>,
    "MessageId": <uuidv4> (Guid),
    "Time": <long>,
    "EventDetails": <object>
  },
  ...
]

The Email webhooks indicate, in the eventType property, which event occurred, and you can use the same endpoint in the configuration for all 5 events, if desired.

The MessageId property is the exact same one returned by the API Email endpoint, on the To / CC / BCC arrays, identifying to which recipient the event pertains to.

Important: The client must ensure that a HTTP 200 (OK) response is returned upon success; otherwise, the webhook will be retried later.

Each webhook contains the eventDetails property, which is an object and contains information related to the specific event that occurred. The eventDetails objects differ depending on the event type and should be processed accordingly. Here are the structures for each event:

Open​

"EventDetails": {
  "CountryCode": <string>,
  "IpAddress": <string>,
  "UserAgent": <string>
}

Click​

"EventDetails": {
  "CountryCode": <string>,
  "IpAddress": <string>,
  "UserAgent": <string>,
  "Link": <string>
}

Bounce​

"EventDetails": {
  "IsBlocked": <bool>,
  "IsHardBouce": <bool>,
  "BounceType": <string>,
  "BounceDescription": <string>
}

Unsubscribe​

"EventDetails": {
  "CountryCode": <string>,
  "IpAddress": <string>,
  "UserAgent": <string>
}

Spam​

"EventDetails": {
  "FeedbackLoopSource": <string>
}

Notes​

  • Special attention should be paid to the fact that in the HTTP request made by Arpoone, the request body is an array that can contain one or more email events, with a up to a maximum total of 1000 per HTTP request;

  • We recommend using the tool https://webhook.site for validation/testing of the webhook functionality, using the "Your Unique URL" value provided by the tool as the endpoint in the webhook configuration;

  • To optimize performance, clients should process the webhooks asynchronously to ensure a short response time to Arpoone's HTTP requests.