You set up the email alert weeks ago. A small, satisfying piece of automation: when the MV Aristos enters the port approach zone, you get a notification. Your team prepares the berth. Customs is warned. The agent is on the way.
The email arrives at 06:14. You read it on the train. You feel briefly organised.
Then you get to the office and find out the Aristos tied up at 04:30.
What happened isn't quite a bug, and it isn't quite a lie. It's the gap between two things that sound almost identical when you read the marketing copy: maritime email alerts and API-based vessel monitoring. They both promise to tell you where your ships are. Only one of them is actually built to.
Six hours is the bad day, to be clear. Most of the time the gap is ten or twenty minutes — long enough to miss the pilot boarding ground, short enough that nobody writes it down. Six hours is what happens when ten or twenty minutes meets a quarantine folder.
The thing about email
Email is, structurally, a notification protocol whose architecture dates to the early 1970s, designed for messages that absolutely do not need to be timely. SMTP itself was formalised in 1982, and it was built to survive a node going down for a week. The entire postal metaphor — inboxes, deliveries, retries — is the wrong shape for "this ship is about to reach the pilot boarding ground."
Here is roughly what happens between an AIS transmission and your inbox. A provider ingests AIS positions from terrestrial receivers and, for open ocean, from satellite constellations. The raw feed itself is fast in some places and slow in others: a Class A transponder on a SOLAS-mandated ship over 300 GT will report every two to ten seconds when underway and every three minutes at anchor; a Class B unit on a smaller coastal trader reports every thirty seconds or so. So already, "real-time AIS" is a range, not a number.
That feed then gets batched, deduplicated, and run through a rule engine on some interior schedule. When a rule fires, a message is queued to SMTP. SMTP hands off to your mail provider, which runs the message through greylisting, spam filters, rate limits, and DMARC checks. Eventually your mail client polls, and the email appears.
It's the stacking that gets you. Each step is harmless on its own. Together they produce a system whose typical latency lives in the minutes and whose worst case lives in the hours, because somewhere in that chain something will occasionally get stuck. Greylisting alone — the spam-prevention trick where unknown senders are politely told to try again later — routinely adds fifteen minutes. A DMARC misalignment can route the alert into a quarantine folder you'll find on Thursday. None of that is the alert provider's fault. It's just what email is: a protocol hardened against spam, not optimised for signalling.
What an API is actually doing
A vessel-tracking API — the kind you'd query from your TMS, your berth-planning tool, or a small internal dashboard — is doing something architecturally different. Instead of pushing a human-readable message through a chain of best-effort hops, it lets your software ask the provider's database a direct question and get a structured answer back.
The most important consequence is that the data is structured. An email says "MV Aristos entered Zone Piraeus-Approach at 04:27." An API response says:
{
"mmsi": 240958000,
"imo": 9776418,
"name": "ARISTOS",
"lat": 37.9421,
"lon": 23.6398,
"sog": 8.4,
"cog": 287,
"nav_status": 0,
"destination": "PIRAEUS",
"eta": "2024-11-12T04:30:00Z",
"timestamp": "2024-11-12T04:27:13Z"
}
(Illustrative example — nav_status: 0 is the raw AIS code for "under way using engine"; most APIs normalise it into a string. The MMSI and IMO are fictional.)
You cannot automate against a sentence. You can do almost anything against that JSON: correlate it with your cargo manifest, trigger a berth-allocation algorithm, update a customer-facing ETA, or fire your own email, on your own infrastructure, with your own latency budget.
Latency, the other thing people care about, mostly collapses — with caveats. A REST call typically returns in a few hundred milliseconds. A WebSocket or streaming endpoint can push position updates within a second or two of the provider receiving them. But that's for vessels within range of terrestrial AIS receivers. For open-ocean ships visible only to satellites, the position you fetch in 200 milliseconds may itself be five to twenty minutes old, depending on the constellation's revisit rate. A fast API does not abolish physics; it just stops adding insults on top.
And then there's the part that sounds like a disadvantage and isn't: an API is pull, not push. You decide when to ask. Forty vessels every thirty seconds, if you want — though at that rate you should probably be on a streaming endpoint instead of hammering REST, both for your own sanity and your provider's rate limits. Webhooks sit in the middle: structured push notifications that give you timing control with the data quality of an API call.
The honest version is that polling has its own pains. Your loop has to actually keep running. Authentication tokens have to keep refreshing. You have to detect gaps when the network blips, because unlike email, nothing screams when a request silently never happens. Whoever told you APIs were free of operational debt was selling something.
The honest case for email
If you are a single operator tracking three or four ships, and you don't have a developer, and your workflow is "look at email, walk down the hall, tell someone" — email alerts are fine. They are, in fact, better than fine. No integration, no API keys, no JSON parsing, no rate-limit management. The five-minute delay doesn't matter, because the human in the loop is also operating on minutes-to-hours timescales.
The problem is what happens when that workflow grows. The moment you have more than a handful of vessels, or more than one person needs the data, or the data needs to flow into another system — email becomes a bottleneck disguised as a feature. You end up with people forwarding alerts to each other. You end up with Outlook rules trying to parse vessel names out of subject lines. You end up, eventually, building a brittle script that reads emails and extracts data from them, which is the saddest possible reinvention of an API. If you find yourself writing an email scraper, the universe is trying to tell you something.
The expensive failure mode
The really costly version of this isn't the dramatic six-hour delay. It's the demurrage dispute.
A vessel arrives at 04:30. Your alert lands at 06:14. Weeks later, in a laytime calculation, your records say the ship arrived at 06:14 — that's the timestamp in your system, because that's when the email came in — and the port's records say 04:30. The difference is real money, and the arbitrator has to pick which timestamp to believe. Notice of Readiness disputes turn on exactly this sort of evidentiary gap. The cheap-looking email alert just became the most expensive line item in the quarter.
Around that sit the quieter costs. Berth windows missed by twenty minutes because the arrival alert was queued behind a spam scan. Customer ETAs that were correct in the provider's database but stale in yours, because nobody received the update. An ops team that has slowly developed a learned distrust of its own alerting system, which is the worst failure mode in any monitoring tool. Once people stop trusting the alerts, they start checking manually, and the automation might as well not exist.
None of these look like the alerting broke. They look like ordinary operational friction. That's what makes them hard to attribute and easy to live with.
Email alerts are a notification layer. An API is a data layer. You can build the first on top of the second — many operations teams do exactly that, sending themselves Slack messages or emails generated from API data they control. You cannot build the second on top of the first without writing an email scraper.
The ship doesn't care when the email arrives. It's already alongside.
Top comments (0)