Backup server
The backup server is a second address running the very same API. It is there for the case when a request to portal.bulkgate.com does not reach its destination at all — the backup host accepts the request and forwards it over a different route.
How the service is built
BulkGate runs on several servers in three geographical locations. If one of them goes down, the remaining ones take the traffic over automatically — nothing changes for your integration and portal.bulkgate.com keeps answering. That case needs no handling on your side. The whole setup is described in Infrastructure.
What this does not cover is the route to us. An outage on the path between your server and ours — at a carrier, at a connectivity provider or anywhere in between — is outside our control, and the request then never reaches us at all. That is what the backup host is for.
The current service status is at bulkgate.status.online.
Address
The host is a one-to-one replacement — paths, parameters, credentials and responses are identical to portal.bulkgate.com. All you swap is the domain:
It works with the same account, the same token and the same credit. There is nothing to set up and nothing to switch on.
Do not use the backup host as your primary address. It can be taken down for maintenance at any time and without notice — it is meant to carry traffic only while the main host is unreachable. Keep portal.bulkgate.com first in the order.
When to switch to it
The backup host solves a connection failure, not a rejected request. To a request the API refused it replies exactly the same way.
Switch when the request gets no answer:
| situation | switch? |
|---|---|
| Connection or read timeout | Yes |
| DNS could not be resolved | Yes |
| Connection refused, network unreachable | Yes |
| HTTP 5xx with no body | Yes |
| A response with an error type (4xx) | No |
429 Too Many Requests (limits |
No |
In the last two cases the API did answer — the request arrived and was evaluated. Repeating it on the backup host returns the same error and only burns another attempt from your limit.
Building the failover into your integration
Keep the addresses in an ordered list and try them one after another. If the connection fails, move on to the next one; if the API answered, return the result as it is.
What to watch out for
A timeout does not mean the message was not sent. The request may have arrived and the response got lost on the way back — a retry on the backup host would then send the message a second time.
That is why you should send duplicates_check enabled on the transactional endpoints. A message with the same text to the same number is dropped within a 5 minute window, so the repeated attempt duplicates nothing.
On promotional endpoints duplicates_check does not protect a retry — it only removes duplicates within a single batch, not across requests. A repeated request is a new batch to it and goes out in full. For bulk sends, rather check whether the first attempt went through before repeating it.
Set a sensible timeout. Without one the client waits for an answer that never comes and never reaches the backup host at all.
API idempotency is in development — a repeated request will be markable so that the API recognises it and returns the result of the original one instead of sending again. That will remove the difference between transactional and promotional endpoints described above. We will document the procedure here as soon as it is available.
Thank you for your feedback.