+49 69 83008980 service@xqueue.com
Benötigen Sie Hilfe?

Im Maileon Help-Center finden Sie umfassende Dokumentationen zu unserem System.

Beliebte Suchanfragen: Importe | Rest-API | Integrationen | SMS

Webhooks – Incoming (Calls from Third-Party- Application towards Maileon)

Sie sind hier:

General

Originally webhooks are a not really standardized way to avoid excessive polling of the progress state by system A which waits for some data of system B in the manner that B just notifies A when it has finished the calculation.

Maileon webhooks can be used from third party applications like Twitter to set up forms that allow setting up registration forms and submittinc contacts to maileon. A webhook is triggered by sending a POST request to a given URL while providing parameters that specify the data for the action to take.

Security

As the data submission is not exactly standardized, different external application use different “standards” and it is important to know, that we have carefully designed the api to be as safe as possible.

  1. Webhook calls are secured using an API-key you can generate in your Maileon account (See “Settings -> Api-Keys”)
  2. Only SSL connections are allowed (using HTTPS). This means, it does not matter if the data is submitted as URL-parameters or in the body: they are encryped.
  3. A webhook call must not be executed directly on the client side (e.g. as a form target or in Javascript) as a client could just investigate the code and read your API-key and use it somewhere else.

Data Submission

The data format of the API is JSON. Complex data will be submitted as JSON and response information (also error messages) will be sumbitted as JSON either (Mime-Type: application/json).
As submitting data using webhooks is not exactly standardized the following ways are often used and have been implemented in the Maileon Webhook API:

  1. All data as URL-parameters (no content-type header required)
    In this case all data is set as URL-parameters. Make sure to URL-encode the data.
    Example: …webhooks?key=xxxxxx&email=max.mustermann@xqueue.com
  2. Content-Type: application/json
    It is possible to submit/  the data partially as URL-parameters and partially, or completely, as an associative array in a JSON-Body.
    IMPORTANT: if a value is set as URL-parameter AND in the body, the body value will override the URL-parameter!
    Example: {"key":"xxxxxx", "email": "max.mustermann@xqueue.com"}
  3. Content-Type: application/x-www-form-urlencoded
    Some applications use this content type and submit the URL-parameter string in the body.
    Example: key=xxxxxx&email=max.mustermann@xqueue.com

Error Messages
In case of errors, e.g. you did not specify a valid API-key, a status code (“401 -> Not Authorized” in this case) will be returned along with a message. Examples:

{"error":{"message":"'key' parameter not found or too many values."}}
or
{"error":{"message":"no such api key"}}

Resources

Create Contact

Creating a contact uses the same configuration possibilities as with our REST-API, see https://support.maileon.com/support/create-contact/.
Please remember: all the following parameters can be used as URL-parameters and in an associative array in the body of the request.

Parameters: Account and contact information

Parameter Default Description
key Required. The API-key of the Maileon-account
email Required. The email address of the contact
external_id Optional. The external ID of a contact.
standard_<FIELDNAME> <FIELDNAME> is the name of the standard contact field to be set, like FIRSTNAME, LASTNAME, etc. Example: standard_FIRSTNAME
See the list of standard contact fields here: standard contact fields.
custom_<FIELDNAME> <FIELDNAME> is the name of the custom contact field, like MyCustomField. Example: custom _ MyCustomField
Important: the fieldname must be written exactly as specified in Maileon (upper and lower case) but must be URL-encoded, e.g. a space must be replaced by a +, etc.
See e.g. https://en.wikipedia.org/wiki/Percent-encoding

Parameters: Service configuration parameters (same as in the REST-API)

Parameter Default Description
permission 1 Specifies the initial permission to be assigned to the contact.Please note: this is the initial permission that is assigned to the contact as soon as it is created. If a double-opt-in process is triggered, the permission is changed to DOI or DOI+ after the contact used the acknowledgement link in the DOI mailing. If the same contact is registered again after already acknowledging the DOI link (and thus, already has Permission 4 or 5) and you call this method with any other permission then 4 or 5 (less valuable), the permission will be ignored, since you already own a valid DOI(+) permission.
Further, if Permission 4 or 5 is already set and the account is set up not to send DOI mailings if there is already a DOI permission, no DOI mailing is triggered when creating the contact a second time.Supported values:
1: none
2: single opt-in
3: confirmed opt-in
4: double opt-in
5: double opt-in plus
6: other
sync_mode 2 Specifies the synchronization option in case a contact with the provided email address already exists.Supported values:
1: update (contact data will be updated)
2: ignore (nothing will be done)
src A string intended to describe the source of the contact. If provided, the string will be stored with the doi process.
subscription_page In case where this method was called by a subscription page, this string offers the possibility to keep track of it for use in reports.
doi false Tells whether a double opt-in process should be started for the created contact. Note that the status code returned for this request does not mean that the doi process succeeded. Supported values are true and false.

Notice: Please be aware that you can set up the behavior for (re-)sending DOI mails in your Maileon account under “Settings” -> “Lists & Contacts” -> „Contact Management“. Here you can define if a DOI mail should be sent to contacts not having finished the DOI process or contacts having a valid DOI permission already.

doiplus false This parameter is ignored if doi is not provided or false. In case the doi process succeeds, Maileon will be allowed to track opens and clicks of the contact.
doimailing This parameter defines the DOI mailing key of the (active) DOI mailing to be used. Be aware, that this is not the ID of the DOI mail but the key that can be specified in the API or UI. It is ignored if doi is not provided or false. If not provided, the default doi mailing will be used.

Response code

  • 200 OK
    This code is the default if everything worked well.
  • 400 Bad Request
    This code is returned if there has been an error processing the data. Usually this happens if e.g. a not valid email has been specified (e.g. max.mustermannQxqueue.com) of a non existing custom field has been specified.
  • 401 Not Authorized
    In case none or an invalid API-key has been submitted, this code will bereturned.
  • 500 Internal Server error
    This is the code we do not expect to happen but if there is something unexpectedgoing wrong, this code will be returned.

Examples

  • Create a contact with the given email address (permission NONE will be used and NO DOI mail will be sent!):
    https://api.maileon.com/webhooks/contacts/email?key=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&email=max.mustermann@xqueue.com&sync_mode=1
  • Create a contact and send the default DOI mailing
    https://api.maileon.com/webhooks/contacts/email?key=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&email=max.mustermann@xqueue.com &sync_mode=1&doi=true
  • Create a contact using the given email address, firstname, lastname the custom field “special date” and send the DOI mail with the key „dh6hdjk9“. The contact will get DOI+ after klicking on the confirmation link in the mail.
    https://api.maileon.com/webhooks/contacts/email?key=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&email=max.mustermann@xqueue.com &sync_mode=1&doi=true&doiplus=true&doimailing= dh6hdjk9&standard_FIRSTNAME=Max&standard_LASTNAME=Mustermann&custom_special+date=12.12.2020

Usage Scenarios

Ever wondered how to connect your Twitter followers with your newsletter easily? Well, how about Twitter Cards?
Using Twitter ads you can set up a card with the offer to register to your newsletter for other registered customers following your stream.
There are a lot of tutorials out there how to set up twitter cards (you must be registered for “Twitter Ads”) and here are the settings for connecting Maileon:

Twitter Card Setup
Inhaltsverzeichnis