ads.txt and sellers.json for Newsletter Ads

A newsletter needs ads.txt and sellers.json only if its ad inventory is sold programmatically to outside buyers through OpenRTB. For direct sponsorships, or for ads bought inside one network's own platform, they change nothing. When outside buyers are involved, ads.txt is a text file the publisher hosts at the root of its website, listing every ad system allowed to sell its inventory, such as mailadx.com, 500123, DIRECT. Sellers.json is the matching file the ad system hosts, saying who seller 500123 is. Most buyers check both before they bid, and skip inventory they cannot verify. For email, that check is the only way a buyer can confirm which publisher an ad request really comes from, because an email has no web page to inspect.

That raises problems the standards were never written for. A newsletter on a hosted platform cannot put a file at the root of a domain it does not own, and many newsletters have no website at all. This post explains the two files, what they mean for newsletters specifically, and what we learned building the checks into MailAdx.

The problem these files solve

Programmatic advertising sells ad space through automated auctions. A bid request arrives at a buyer saying, in effect, "here is an ad slot on site X, from seller Y, what will you pay?" For years, nothing stopped a seller from writing any site it liked in that request. Junk inventory could be labelled as a premium news site and sold at premium prices. The industry called it domain spoofing, and it was common enough to distort the market.

The IAB Tech Lab's answer was a set of standards that let a buyer check each claim in a bid request against a file only the right party can publish:

• ads.txt, published by the publisher, lists who may sell its inventory.
• sellers.json, published by each ad system, says who each of its seller accounts belongs to.
• SupplyChain (schain), carried inside the bid request, lists every company that handled the request on its way to the buyer.

A buyer that receives a request claiming to be from example.com, sold by MailAdx as seller 500123, fetches example.com/ads.txt and looks for mailadx.com, 500123, DIRECT. Then it fetches mailadx.com/sellers.json and looks up seller 500123. If both match, the claim is verified. If either is missing, most large buyers do not bid.

Why email needs this more than websites do

On a website, a buyer has other ways to check where an ad will appear. It can crawl the page, read its content and see what kind of site it is.

An email has no page. An ad in a newsletter is an image loaded when the reader opens the email, inside Gmail, Apple Mail or Outlook. There is no URL to crawl and no content a buyer can inspect in advance. The only claim about where the ad will appear is the domain the ad system writes into the bid request. Without ads.txt and sellers.json, email inventory looks exactly like spoofed inventory: an unverifiable claim from a seller the buyer has no way to check.

So for a newsletter that wants programmatic demand from outside buyers, these files are not optional extras. They are the price of being bid on at all. The post on programmatic email advertising covers how that demand works, and the ad server page explains where outside bids sit alongside direct campaigns.

When a newsletter does not need them

It is worth being clear about when none of this applies, because it is a common source of wasted effort.

Direct sponsorships are agreed between the publisher and the advertiser. No auction, no outside buyer, no file to check. The sponsor knows exactly whose newsletter they bought.

Ads bought inside one network's own platform also skip it. When an advertiser buys newsletter placements directly in MailAdx's own interface, MailAdx already knows every publisher, because each one signed up and was approved. The buyer is not relying on a claim in a bid request.

Only open, programmatic demand from outside buyers needs verification. In MailAdx terms that is the OpenRTB channel, where we send bid requests to demand-side platforms we do not control. That is where ads.txt and sellers.json matter. The posts on direct-sold newsletter ads and sponsorships versus programmatic ads explain how the channels differ.

How an ads.txt line works

An ads.txt file is plain text, one authorised seller per line:

# ads.txt for example.com
OWNERDOMAIN=example.com
mailadx.com, 500123, DIRECT
otherexchange.com, pub-98765, RESELLER, a1b2c3d4e5f6
CONTACT=ads@example.com

Each line has three or four fields:

1. The ad system's domain, such as mailadx.com. It must match the domain the ad system uses in its sellers.json.
2. The publisher's account ID in that system. This must match exactly the seller ID the system sends in bid requests and lists in its sellers.json.
3. The relationship. DIRECT means the publisher owns the account and is paid directly. RESELLER means someone else's account is being used to sell the publisher's inventory.
4. Optionally, a certification ID for the ad system from the Trustworthy Accountability Group.

Version 1.1 of the specification, released in 2022, added variables. OWNERDOMAIN names the business that owns the site, and buyers compare it with the domain in the seller's sellers.json entry. MANAGERDOMAIN names a company that manages the site's monetisation. CONTACT gives a contact address.

The file must live at the root of the registrable domain: example.com/ads.txt, not blog.example.com/ads.txt or example.com/newsletter/ads.txt. Buyers crawl the root. For a domain like blog.example.co.uk, the root is example.co.uk, which is why our checker uses the public suffix list rather than simply stripping the first label.

The newsletter problem: shared platform domains

Here is where newsletters break the model. A newsletter published at yourname.substack.com or yourname.beehiiv.com does not own the root domain. Its ads.txt would have to be at substack.com/ads.txt, which the platform controls. The publisher cannot add a line there, and the platform will not add one for every writer and every ad system.

The same is true of newsletters that live entirely on platform domains such as ghost.io, medium.com, Mailchimp's hosted pages, Kit's landing pages, wordpress.com and blogspot.com. In each case the root belongs to someone else.

Our checker recognises these domains and reports them as a shared platform domain without fetching anything, because no line the publisher can add would ever be found there. That tells the publisher the honest answer straight away: to be verifiable for programmatic demand, they need a domain of their own.

It does not need to be a big website. A one-page site on a domain the publisher owns, with the newsletter's signup form and an ads.txt file at its root, is enough. Many hosted newsletter platforms also let a publication use its own custom domain, and moving to one is worth doing for other reasons too, as the post on deliverability and ad revenue explains.

Newsletters with no website at all

Some newsletters have no web presence beyond the email itself. When we built these checks, fewer than half of the active publishers on our platform had a website listed at all. No domain means no ads.txt, and no ads.txt means outside buyers cannot verify the inventory.

That is not a defect to work around. It is a fact about supply, and it shapes which demand a newsletter can access. A newsletter with no domain can still sell direct sponsorships and receive ads from advertisers buying inside a network's own platform. It cannot be sold through open programmatic auctions to buyers who verify, which today is most of them.

How sellers.json works

Sellers.json is the ad system's side of the check. MailAdx publishes ours at mailadx.com/sellers.json. Its shape looks like this:

{
  "version": "1.0",
  "contact_email": "support@mailadx.com",
  "sellers": [
    { "seller_id": "500123", "seller_type": "PUBLISHER",
      "name": "Example Media Ltd", "domain": "example.com" },
    { "seller_id": "500124", "seller_type": "PUBLISHER",
      "is_confidential": 1 }
  ]
}

The rules that matter:

• seller_id must equal the ID in the publisher's ads.txt line, the ID in the bid request, and the seller ID in the request's supply chain. One identity, the same everywhere.
• seller_type is PUBLISHER for a seller that owns its inventory, INTERMEDIARY for one reselling others' inventory, or BOTH. Every MailAdx newsletter publisher is a PUBLISHER. A network reselling other publishers' newsletters through an exchange would be listed as an INTERMEDIARY.
• name is the legal entity that gets paid, and domain is that entity's business domain.
• is_confidential hides the name and domain. It exists so that individuals are not forced to publish their names, but many buyers rank confidential sellers lower or exclude them, because they cannot see who they are paying.

Four decisions we had to make

Building this for MailAdx meant answering questions the standards leave to the ad system. Each answer affects publishers, so they are worth stating.

Seller IDs are numeric, start at 500001 and are never reused. Our internal publisher identifiers are long database IDs, which are awkward to copy into a text file and expose internal structure. A short, stable number is easier to publish and check. An ID that once belonged to a publisher is never given to another, because a buyer may have cached the old pairing.

Individuals are confidential by default. Many newsletters are run by one person under their own name. Publishing that name in a public file should be their choice, so it is opt-in. We tell publishers plainly that disclosing a business name and domain usually helps with buyers.

The file must answer on the bare domain, with no redirect. Our website redirects mailadx.com to www.mailadx.com, like most sites. Our first check of mailadx.com/sellers.json found exactly that: a redirect to the www address, which then returned our website's HTML "not found" page. Buyers expect the file at the domain they have in the ads.txt line, answering directly. We added a specific route ahead of the redirect so mailadx.com/sellers.json answers with the file itself, and checked it from outside.

Passing the ads.txt check is also proof of domain ownership. Until now, a publisher's website in our system was whatever they typed. Only the owner of example.com can publish mailadx.com, 500123, DIRECT at its root, so a passing check proves control of the domain. Listing a publisher as an authorised seller for programmatic demand now requires a passing check. An administrator can override that, but the override is recorded with the reason.

Checking a publisher's ads.txt, safely

Telling a publisher to add a line is the easy part. Knowing whether they did, and keeping on knowing, is where most of the work went. Every MailAdx publisher now has an Authorized Sellers page showing their domain, the exact line to publish with a copy button, the recommended OWNERDOMAIN line, and a status. They can press Check now and get an answer within about fifteen seconds, and every publisher with a domain is rechecked automatically each day.

The statuses are deliberately specific, because "not authorised" on its own does not tell anyone what to fix:

Status                    Meaning                                      What to do
────────────────────────  ───────────────────────────────────────────  ─────────────────────────────
AUTHORIZED                Our domain, your exact ID, DIRECT            Nothing
LINE_MISSING              File found, no MailAdx line in it            Add the line
WRONG_ID                  MailAdx line present, different ID           Correct the ID (shown)
WRONG_RELATIONSHIP        Your ID, but marked RESELLER                 Change to DIRECT
NO_FILE                   No ads.txt at the root domain                Create the file
NOT_A_TEXT_FILE           A web page was served instead of the file    Fix the server route
FETCH_ERROR               The site could not be reached                Check the domain
SHARED_PLATFORM_DOMAIN    Substack, beehiiv, Ghost, Medium and others  Use a domain you own
NO_DOMAIN                 No website recorded                          Add your website

NOT_A_TEXT_FILE deserves a word, because it is the most common surprise. Many website builders answer any unknown address with a styled "page not found" page and a success status, instead of a real error. A naive checker sees a successful response and starts parsing HTML as ads.txt. Ours checks that what came back is actually a text file.

Fetching files from addresses that users type is also a security risk. A malicious entry could point the checker at an internal address inside our own network. So the fetcher resolves the address on every redirect hop and refuses private, loopback, link-local and cloud metadata addresses. It only uses the standard web ports, caps the response at 1 MB, and follows at most five redirects, of which at most one may leave the original domain, which is also what the ads.txt specification allows. Before showing it to anyone, we confirmed on the live system that a domain resolving to a local address is refused.

One honest result from those first live checks: our own domain fails. mailadx.com/ads.txt holds a placeholder, because MailAdx sells no ad space on its own website, so there is no line to list. The checker correctly reports the file as present but without a MailAdx line. A checker that passed its author's own site would have been less convincing.

What verification does to fill rate

Publishers sometimes ask whether adding an ads.txt line will raise their revenue. The honest answer is that it removes a ceiling rather than adding demand.

Without a valid line, outside buyers that verify simply do not bid, so the slot falls back to whatever direct or network demand exists, or goes unfilled. With a valid line, those buyers can compete for the slot. Whether they do depends on the audience, the price floor and the buyer's targeting. A newsletter with a strong audience and a sensible floor gains more from verification than one whose floor is above what programmatic buyers pay for email.

So treat ads.txt as the precondition and the floor as the lever. The fill rate optimisation guide and the floor CPM guide explain how to set a floor that lets programmatic demand compete without underselling your sponsorships, and the eCPM and fill rate calculator shows how the two interact. If you sell sponsorships too, a media kit that mentions your verified status tells agencies you are set up for programmatic buying as well as direct deals.

Google Ad Manager and email

One question comes up often enough to address directly: can a newsletter sell its ad space through Google Ad Manager's open auction, once its ads.txt is in place?

Under Google's current rules, generally not. Section 3.1 of the Ad Manager Partner Guidelines lists placements where Open Auction ads are not allowed, and it includes ads placed in emails, including email newsletters, except where Google expressly permits it. Google has been testing newsletter ads in Ad Manager, but as reported in the trade press, that test covers reservation and programmatic guaranteed deals rather than the open auction.

So for newsletters, outside programmatic demand comes from other buyers, and ads.txt and sellers.json are what those buyers check. A newsletter publisher hoping to plug Google's open auction into their issues should read the guidelines before building anything around it.

What comes next: the supply chain object

The third standard, the supply chain object, travels inside each bid request and lists every company that handled it, each identified by its domain and its seller ID. A buyer checks every link against the matching sellers.json. For MailAdx, which sells its publishers' inventory directly, the chain is a single link: MailAdx, with the publisher's seller ID.

We have not yet connected an outside demand-side platform, so the supply chain object in our bid requests is the step that follows when the first buyer integrates. The seller IDs, sellers.json and the ads.txt checks come first because a buyer cannot verify anything without them, and because publishers need time to publish their lines before any buyer looks.

A checklist for newsletter publishers

1. Decide whether you need it. If you sell only direct sponsorships, you do not. If you want programmatic demand from outside buyers, you do.
2. Make sure you own a domain. A newsletter that lives only on a platform subdomain cannot be verified. A simple one-page site on your own domain fixes that.
3. Publish the exact line your ad network gives you at yourdomain.com/ads.txt, character for character, marked DIRECT.
4. Add OWNERDOMAIN= with your business domain, matching what your ad network lists for you in its sellers.json.
5. Check the file answers as plain text at the root, without redirecting to an HTML page.
6. Keep every line you still use. Removing an ad system's line cuts off its demand the next time buyers crawl.
7. Decide about disclosure. Being listed with your business name and domain usually helps with buyers. Being confidential protects your privacy at some cost in demand.

MailAdx publishers can find their line and status under Authorized Sellers in the publisher dashboard. The publisher product page explains how programmatic demand fits alongside sponsorships, and the email RTB yield post covers what programmatic demand can add to a newsletter's revenue.

A checklist for buyers

If you buy newsletter inventory programmatically, the same files protect you. Confirm that the publisher's ads.txt lists the seller as DIRECT, that the seller appears in the ad system's sellers.json with a real name and domain, and that the domains agree. Be cautious with confidential sellers and with supply that cannot be verified at all. And remember that verification proves who is selling, not how good the audience is. Traffic quality is a separate question, covered in our post on Apple Private Relay and fraud filters, and the brand safety guide covers what publishers do to protect advertisers.

Advertisers who would rather buy newsletter inventory without running their own verification can buy inside MailAdx directly; the advertiser page explains how. Publishers and advertisers can both create an account, and the glossary defines the terms used here.

Frequently asked questions

Do newsletters need an ads.txt file?

Only if their ad inventory is sold through programmatic auctions to outside buyers. Most buyers check ads.txt before bidding and skip inventory they cannot verify. Newsletters that sell only direct sponsorships, or whose ads are bought inside one network's own platform, do not need one.

Where does a newsletter put its ads.txt file?

At the root of the publisher's own registrable domain, such as yourdomain.com/ads.txt. Buyers crawl the root, not a subdirectory or a subdomain. The file must be served as plain text and should not redirect to an HTML page.

Can a Substack or beehiiv newsletter have an ads.txt file?

Not on the platform's own subdomain. A newsletter at name.substack.com would need the file at substack.com/ads.txt, which the platform controls. To be verifiable for programmatic demand, the newsletter needs a domain it owns, either for a simple website or as the publication's custom domain.

What is the difference between ads.txt and sellers.json?

ads.txt is published by the publisher and lists the ad systems allowed to sell its inventory, with its account ID in each. sellers.json is published by the ad system and says who each seller account belongs to. A buyer checks that both agree before bidding.

What does DIRECT mean in ads.txt?

It means the publisher holds the account in that ad system and is paid directly through it. RESELLER means another company's account is used to sell the publisher's inventory. A newsletter publisher with its own account in an ad network should use DIRECT.

Can newsletter ads be sold through Google Ad Manager's open auction?

Generally not. Google's Ad Manager Partner Guidelines list ads in emails, including email newsletters, among placements where Open Auction ads are not allowed, except where Google expressly permits it. Google's newsletter ads test has been reported as limited to reservation and programmatic guaranteed deals.

Should I mark my seller entry as confidential?

It is a trade-off. Confidential entries hide your name and domain, which protects individuals' privacy, but many buyers rank confidential sellers lower or exclude them because they cannot see who they are paying. Publishing a business name and domain usually helps demand.