Buttondown Documentation

Buttondown Documentation

© 2016–2025 Buttondown LLC.

TwitterGitHubLinkedInMastodonBlueskyFacebook

Email status

As a helpful primer for the diagram below, here's a quick run-through.

Edges

  • Animated edges indicate state transitions that Buttondown performs automatically.
  • Static edges indicate state transitions that you, the newsletter owner, can perform (either through the API or the web interface).
flowchart LR
  in_flight[In flight] animated@--> Sent
  in_flight --> Paused

animated@{animate: true}

Nodes

  • Rounded rectangles indicate entry points for emails (such as an RSS feed or the web interface).
  • Squares indicate actual statuses.
  • Flags represent events that are created in response to state changes.
flowchart
  example.com/rss.xml([example.com/rss.xml])
  Draft
  email_sent>email.sent]
flowchart
  example.com/rss.xml([example.com/rss.xml]) e1@--> managed_by_rss[Managed by RSS]
  draft[Draft] --> scheduled[Scheduled]
  api([POST api.buttondown.com/v1/emails]) --> draft
  api([POST api.buttondown.com/v1/emails]) --> scheduled
  draft --> about_to_send[About to send]
  about_to_send e2@--> in_flight[In flight]
  scheduled e3@--> in_flight
  in_flight --> paused[Paused]
  paused --> in_flight
  in_flight e8@--> throttled[Throttled]
  throttled e9@--> in_flight
  managed_by_rss[Managed by RSS] e4@--> draft
  managed_by_rss e5@--> about_to_send
  in_flight e6@--> sent[Sent]
  sent e10@--> resending[Resending]
  resending e11@--> sent
  sent e7@--> email_sent>email.sent]
  e1@{ animate: true }
  e2@{ animate: true }
  e3@{ animate: true }
  e4@{ animate: true }
  e5@{ animate: true }
  e6@{ animate: true }
  e7@{ animate: true }
  e8@{ animate: true }
  e9@{ animate: true }
  e10@{ animate: true }
  e11@{ animate: true }
  click email_sent href "event-types#email.sent"

(Transactional emails are intentionally omitted from the diagram above, as they don't enter the workflow at all.)

That is, obviously, a lot to take in. If you're just trying to understand for the first time how emails move through the workflow, here's a simplified diagram with some edge cases removed:

flowchart
  api([POST api.buttondown.com/v1/emails]) --> draft
  api([POST api.buttondown.com/v1/emails]) --> scheduled
  draft[Draft] --> scheduled[Scheduled]
  draft --> about_to_send[About to send]
  about_to_send e2@--> in_flight[In flight]
  scheduled e3@--> in_flight
  in_flight e6@--> sent[Sent]
  e2@{ animate: true }
  e3@{ animate: true }
  e6@{ animate: true }

Represents the state of an email.

No action is required to move from one state or another; Buttondown internally handles the transitions, and exposing the status is for observability purposes only.

Draft

Type
draft
Description

Draft emails are only visible to you and are not sent out to subscribers.

About to send

Type
about_to_send
Description

This email has been queued to send out to subscribers, and will be sent automatically within a few minutes.

If you're seeing that an email you just sent out is 'stuck' here, worry not — Buttondown sometimes takes a little bit longer to send out emails to ensure deliverability, but once it's marked as 'about to send' it will get sent out.

Scheduled

Type
scheduled
Description

This email has been scheduled to send out to subscribers at a specific time. This specific time is available on the email as its publish_date.

In flight

Type
in_flight
Description

This email is currently being sent out to subscribers, and is visible in your web archives if enabled.

Some emails, especially those with large subscriber lists, may take a while to send out — Buttondown sends emails out in batches to ensure deliverability, so if you're seeing an email 'stuck' here, it's because our systems have detected that that's the optimal way to reach your subscribers.

Imported

Type
imported
Description

This email was imported from another service, and is visible in your web archives if enabled.

Managed by RSS

Type
managed_by_rss
Description

This email was created by an external feed, and has not yet been finalized and sent out by Buttondown.

Deleted

Type
deleted
Description

This email has been deleted, and is no longer visible in your web archives.

Paused

Type
paused
Description

This email has been paused, and is not visible in your web archives.

Sent

Type
sent
Description

This email has been sent out to subscribers, and is visible in your web archives if enabled.

Errored

Type
errored
Description

This email has encountered an error while sending out to subscribers, and is not visible in your web archives.

Throttled

Type
throttled
Description

This email is in the process of being sent out, but is being intentionally sent slowly to ensure deliverability.

Resending

Type
resending
Description

This email is in the process of automatically being resent to subscribers by Buttondown's systems in order to make sure all subscribers have received it.

Transactional

Type
transactional
Description

This email is a transactional email used by a core workflow in your newsletter or Automations, and is not visible in your web archives nor sent out to subscribers.

Referenced by

2025-04-17Buttondown CLICustomizing your email dashboardScheduling emails via the API

© 2016–2025 Buttondown LLC.

TwitterGitHubLinkedInMastodonBlueskyFacebook