---
title: "Application Programming Interface (API)"
description: "An API is a set of protocols and tools that let software applications and services communicate and share functionality with each other."
url: "https://mailmum.io/glossary/application-programming-interface-api/"
---

# Application Programming Interface (API)

An API (Application Programming Interface) is a defined contract that lets one
piece of software use the functionality of another. It specifies which
operations exist, what they expect, and what they return — without the
caller needing to know how the other side is implemented.

In email systems the term almost always means an HTTP API: a REST or JSON
interface used to submit messages, query delivery status, manage suppression
lists, or look up reputation data.

## What is the difference between sending by API and sending by SMTP?

Both end with a message being delivered by an
[MTA](https://mailmum.io/glossary/mail-transfer-agent-mta/). The difference is the handover.

With SMTP you open a TCP session, conduct a multi-step conversation, and receive
a response code per recipient:

```txt
220 mx.example.net ESMTP
EHLO client.example.org
MAIL FROM:<sender@example.org>
250 2.1.0 Ok
RCPT TO:<recipient@example.net>
250 2.1.5 Ok
DATA
354 End data with <CR><LF>.<CR><LF>
```

With an HTTP API you post the message as structured data and get one response:

```sh
curl -X POST https://api.provider.example/v1/messages \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "from": "sender@example.org",
        "to": ["recipient@example.net"],
        "subject": "Order confirmation",
        "text": "Thank you for your order."
      }'
```

```json
{"id": "0f3c9a2e-6b41-4d0a-9d1e-3c7a2b8e5f10", "status": "queued"}
```

The trade-offs are practical rather than philosophical:

| | SMTP | HTTP API |
| --- | --- | --- |
| Authentication | SMTP AUTH credentials | bearer token or API key |
| Firewall | port 25/587/465, often blocked outbound | port 443, almost never blocked |
| Result | per-recipient SMTP status code | one queue ID, outcome later via webhook |
| Portability | works with every provider | provider-specific payload |
| Attachments | native MIME | base64 in JSON, with size limits |

The most consequential row is the third. An API accepts responsibility for the
message and returns immediately; the actual delivery outcome arrives
asynchronously. If you never consume those events, you have no idea whether the
mail was delivered.

## What are webhooks, and why do they matter here?

A webhook is the reverse direction: the provider makes an HTTP request to a URL
you host whenever something happens to a message. This is where API-based
sending gets its delivery feedback.

```json
{
  "event": "bounced",
  "message_id": "0f3c9a2e-6b41-4d0a-9d1e-3c7a2b8e5f10",
  "recipient": "recipient@example.net",
  "code": "550",
  "reason": "5.1.1 User unknown"
}
```

Those events are the API equivalent of a [bounce
message](https://mailmum.io/glossary/bounce-message/) and of an
[ARF report](https://mailmum.io/glossary/abuse-reporting-format-arf/), and they carry the same
obligation: a hard bounce or a complaint must result in suppression. Skipping
that step drives the bounce and complaint rates that get sending IPs
[blacklisted](https://mailmum.io/glossary/ip-blacklisting/).

Anything receiving webhooks needs to verify the signature the provider sends,
respond quickly and queue the work rather than processing inline, and tolerate
duplicates &mdash; retries mean the same event can arrive more than once.

## Which other email APIs are worth knowing?

* **Blocklist and reputation lookups.** Most DNSBLs are queried over DNS rather
  than HTTP, but several operators also offer an HTTP API for bulk queries and
  for delisting requests.
* **RIR and WHOIS data.** RIPE, ARIN and APNIC expose their registry data over
  HTTP, which is how tooling resolves an IP address to its
  [ASN](https://mailmum.io/glossary/autonomous-system-number-asn/) and its abuse contact
  automatically instead of parsing `whois` output.
* **Mailbox APIs.** Microsoft Graph and the Gmail API read and send mail on
  behalf of a user via OAuth, replacing IMAP and SMTP AUTH for applications that
  act as a user.

## What should you watch out for with email APIs?

* **Credential scope and rotation.** An API token that can send mail is as
  sensitive as an SMTP password, and it usually sits in a config file or a CI
  variable where it is easier to leak. Scope tokens to what they need and rotate
  them.
* **Silent success.** A `200 OK` means accepted for delivery, nothing more.
  Treating it as proof of delivery is the single most common mistake in
  API-based sending.
* **Rate limits.** Providers throttle, and a retry loop that ignores `429`
  responses turns a temporary limit into a backlog.
* **Lock-in.** The payload format is provider-specific. Keeping message
  construction separate from the transport makes switching providers, or falling
  back to SMTP, a contained change.