Passa al contenuto principale

Best practices

The following recommendations will help you:

  • Save time
  • Ensure that you are using the API elements, attributes, methods and calls correctly
  • Get the most out of the Contactsend SOAP API

Do not leave a session open​

Unless you know that you are going to continue working within a short period of time, we recommend that you end the current session and start a new one later. If the session is idle for more than 15 minutes, the relevant authorization token becomes invalid, however, for security reasons you should not rely on this. See Contactsend SOAP API > Using services for more details.

Do not assume that the API is always available​

There are several reasons why the API may not be available from time to time. Force majeure, system maintenance, or temporary resource shortages may each influence availability. Contactsend uses a number of infrastructure and architecture best practices, to protect against unavoidable resource failures and provide a level of system resilience as a result. But the nature of the web itself highlights the need to write code so that the potential impact of temporary problems is reduced as far as possible.

We recommend that you always write your code in a way that ensures your software and business logic will survive a failed API call. This is best practice for any software-as-a-service integration, but it is frequently overlooked. This is particularly the case when time is short and extensive testing cannot be performed, so we would like to reiterate the importance of this principle here.

If you have to deploy an non-resilient application because of, for example, pressing deadlines, we recommend that you always try to ensure that resilience is added as soon as possible. Otherwise, problems will occur sooner or later. Fixing problems manually because the application does not have the logic to recover by itself, is frequently the cause of even more problems and frustration.

Expect and manage errors​

We recommend that you do not assume that an API call has been completed, simply because the call was made. For example, Contactsend may answer the call with an error, which you need to check and act upon accordingly. If you don’t, further problems may well be the result.

Use an exception wrapper around your calls​

Most modern development environments allow for exception handling, which greatly simplifies error condition management. We recommend that you use it to ensure any unexpected condition does not result in your application losing control of what is happening.

Your application should have two timeout settings:

  • The maximum time it should take to connect to your remote host
    • We recommend a connection timeout of 30 seconds in your SOAP Web services client
  • How long the socket connection should wait for a response from the server
    • We recommend a default socket timeout of 300 seconds (5 minutes)

Use a timeout wrapper around your calls​

If you use exception handling, a timeout will simply be another kind of trapped/managed exception.

If you cannot use exception handling for whatever reason, we recommend that you at least use timeout protection against unending API calls. If your application hangs indefinitely while waiting for a response, a periodic job could, for example, be reinitialized and run at the same time as a copy of itself. This is often the cause of serious problems and data inconsistencies.

Use established daemon coding practices to avoid unwanted multiple instances of your application being run​

You could use a file, table, or record lock in a database, or similar techniques, to ensure that only one application instance at a time can be run. Turning part of an application into a daemon is simple and effective, but without the appropriate experience, it is also easy to make errors. This is, however, a recognized problem and there are many open source or commercial tools and libraries available to help resolve it.

Conversely, if you code your application so that multiple instances can be run, we recommend that you ensure it behaves as intended.

Do not make more than one API call per second​

While this is not an automatic system-defined limit, we do ask you to to contact your project manager, account manager or Contactlab customer care in advance and allow us to manage your needs effectively.

API retries and rescheduling calls​

Retry failed calls a reasonable number of times​

We at Contactlab focus on giving our customers a first-class API availability rate, and make considerable efforts to improve our already high standards of service. If there is, for example, a timeout, resource shortage, or similar error while calling an API, most of the time it will not happen again, if the call is repeated a little later.

We recommend that you always retry a failed call a reasonable number of times. Even if the exception error code indicates that the problem is permanent, it will do no harm to retry the call.

Do not retry failed calls immediately​

While retrying is recommended, you should not repeat an API call immediately. If, for example, a resource shortage or conflict causes the initial error, an immediate retry will probably return the same error and needlessly occupy available resources. As a result, we recommend that you wait a while before retrying.

Retry and rescheduling recommendations​

We recommend that you apply the following approach:

  • Retry at least six times, if needed.
  • Wait at least 30 seconds between retries.
  • If, after a minimum of six retries with intervals of at least 30 seconds, the API call still does not complete successfully, reschedule the call for 30 minutes later.

We recommend that you use this approach as many times as you see fit. If you have reasons not to do so, for example, the relevant delivery should never start after a certain time, then tailor the suggested steps to your needs.

A web connectivity problem generally does not last more than a few hours. If you persist with the recommended approach, the job will be completed in the shortest practical time.

Avoid using addSubscriber or addSubscribers when you want to add a substantial number of records​

We recommend that you set up up a DataExchange, whenever you need to add more than approximately 500 records, or 1MB of data, to your database(s). While this is not an automatically applied limit, we do ask you to contact your project manager, account manager or Contactlab customer care in advance and allow us to manage your needs effectively.

Setting up a DataExchange is much more efficient when managing a large data set.

Check the Contactsend user interface for maintenance alerts​

We always provide at least two working days notice of maintenance activities. Please note, however, that the Italian business calendar applies to any notifications.