# API, or SMTP?

Postmark gives you two ways to send the same email: an HTTP API and a standard SMTP server. Here's how to pick the one that fits the way your app is built.

<Verdict tone="blue" title="The short answer">
Use the **API** for anything you're building now. Use **SMTP** when your app or plugin only knows how to send over SMTP, or when you want to switch to Postmark by changing a setting instead of your code.
</Verdict>

## Which one sounds like you?

<PickOne
  a={{
    name: "API",
    tone: "blue",
    title: "Choose the API if…",
    lead: "You're writing the sending code, or you can change it.",
    points: [
      "You want to know right away whether a send worked, with a message ID you can track",
      "You send to many people at once: batch up to 500 messages in one call",
      "You'd like an official library to handle retries and request details",
      "You'd rather hear about a problem when you send than in a bounce report later",
    ],
  }}
  b={{
    name: "SMTP",
    tone: "yellow",
    title: "Choose SMTP if…",
    lead: "Your app already sends over SMTP and you'd rather not rewrite it.",
    points: [
      "Your app, framework or plugin only has SMTP settings to fill in",
      "You're moving from another provider and want to change a setting, not code",
      "You want to try Postmark quickly before committing to a rewrite",
      "You're fine learning about failures through bounce webhooks or the bounces API",
    ],
  }}
/>

## Side by side

<Compare
  a={{ name: "API", tone: "blue" }}
  b={{ name: "SMTP", tone: "yellow" }}
  rows={[
    [
      "How you connect",
      "An HTTPS request with a JSON body, with your Server API token in a header",
      "A standard SMTP connection to smtp.postmarkapp.com on port 25, 2525 or 587, with STARTTLS",
    ],
    [
      "What you change",
      "Your sending code, usually through an official library",
      "A configuration setting",
    ],
    [
      "When a send fails",
      "You get an answer to every request: success with a message ID, or an error code, for example when a recipient is inactive",
      "Postmark accepts the message and reports problems afterward, through bounce webhooks or the bounces API",
    ],
    [
      "Sending to many people",
      "The batch endpoint sends up to 500 messages per call",
      "Not part of SMTP. Use the API for batches",
    ],
    [
      "Retries",
      "Many official libraries retry on network errors for you",
      "Up to your SMTP client",
    ],
    [
      "Tags",
      "A Tag field on the request",
      "An X-PM-Tag header, one tag per message, up to 1,000 characters",
    ],
    [
      "Message stream",
      "A MessageStream field on the request",
      "An X-PM-Message-Stream header, or an SMTP Token made for that stream",
    ],
    [
      "Credentials",
      "Your Server API token, in the X-Postmark-Server-Token header",
      "Your Server API token as both username and password, or an SMTP Token (an access key and a secret key)",
    ],
  ]}
/>

## Quick check

If one of these is true for you, here's where it points.

<Rules
  a={{ name: "API", tone: "blue" }}
  b={{ name: "SMTP", tone: "yellow" }}
  items={[
    { when: "You're starting a new project", pick: "a" },
    { when: "You need to know right away if a send failed", pick: "a" },
    { when: "You send to hundreds of people at once", pick: "a" },
    { when: "Your app or plugin only has SMTP settings", pick: "b" },
    { when: "You want to switch providers without touching code", pick: "b" },
    { when: "You're not sure", pick: "a" },
  ]}
/>

<Note tone="blue" title="You're not locked in">
Both use the same Server API token and the same message streams, so starting with SMTP and moving to the API later doesn't mean starting over.
</Note>

## What each one looks like

<div className="decide-pair">

<div>

**With the API**

```bash
curl "https://api.postmarkapp.com/email" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Server-Token: server token" \
  -d '{
    "From": "you@yourdomain.com",
    "To": "friend@example.com",
    "Subject": "Hello from Postmark",
    "TextBody": "It works!",
    "MessageStream": "outbound"
  }'
```

</div>

<div>

**With SMTP**

```text
Server    smtp.postmarkapp.com
Port      587 (25 and 2525 also work)
Security  STARTTLS
Username  your Server API token
Password  your Server API token
Header    X-PM-Message-Stream: outbound (optional)
```

</div>

</div>

<Note tone="yellow" title="Sending a broadcast over SMTP?">
Broadcast messages use their own server, smtp-broadcasts.postmarkapp.com. Not sure whether you're sending a broadcast? Read [Transactional or broadcast?](/transactional-or-broadcast)
</Note>

## What do you want to do next?

<Paths
  items={[
    {
      title: "Send with the API",
      body: "The request format, headers and examples, one page at a time.",
      to: "/user-guide/send-email-with-api",
      tone: "blue",
      icon: "Mail",
    },
    {
      title: "Send with SMTP",
      body: "Connection details, authentication and the differences from the API.",
      to: "/user-guide/send-email-with-smtp",
      tone: "yellow",
      icon: "Inbox",
    },
    {
      title: "Use an official library",
      body: "Libraries for TypeScript, Python, Ruby, .NET, Java, PHP and more.",
      to: "/libraries/official",
      tone: "mint",
      icon: "Sparkles",
    },
    {
      title: "Try it without sending",
      body: "Sandbox mode lets you test your setup without delivering real email.",
      to: "/user-guide/sandbox-mode",
      tone: "slate",
      icon: "Layers",
    },
    {
      title: "How SMTP works",
      body: "A friendly guide to the protocol behind it all.",
      to: "/guides/everything-you-need-to-know-about-smtp",
      tone: "red",
      icon: "Globe",
    },
  ]}
/>

Prefer a longer read with Python examples? See [Sending mission-critical emails in Python: SMTP or API?](https://postmarkapp.com/blog/sending-mission-critical-emails-in-python-smtp-or-api) on the Postmark blog.
