Sending identities

A sending identity is one verified domain. It has its own DKIM keys, its own MAIL FROM subdomain, and — the part that matters — its own reputation with Gmail, Outlook and everyone else.

Most senders start with one. That is fine until the day a campaign draws complaints, because mailbox providers do not distinguish your newsletter from your password resets when both leave from example.com. The reset lands in spam, and the first you hear about it is a support ticket.

Splitting the traffic across two identities keeps that from happening. A common shape:

Both are subdomains of one root you already own, so both are one DNS zone and one set of records to publish.

Adding one

Add a domain the way you always have, in Settings → Domains. Once Sendly can see the root you are typing, it offers mail. and news. and says what each is for. Picking one assigns the stream and makes it your default for that stream in the same step.

The root itself is still addable, and it is still the fallback. A domain with no stream carries both, which is exactly what every domain added before this feature does.

What the assignment actually does

It is enforced, not a label.

• A send with no from address goes out on your default identity for its stream, using that identity's default sender. Transactional sends resolve the transactional identity; campaigns resolve the marketing one.
• A send that names a from address uses it — that is the per-send override — but the address still has to be on an identity your project owns AND one that carries this stream. Sending a campaign from your transactional identity is refused with 403, naming the identity and both streams.

So the separation is a property of the mail, not a setting somebody has to remember.

curl -X POST https://api.sendly.now/api/v1/campaigns \
  -H "Authorization: Bearer $SENDLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "September", "from": "hello@mail.example.com", ... }'

# 403
# "mail.example.com" is the transactional sending identity for this project, so it cannot
# carry marketing mail. Send from the marketing identity, or unassign this one to let it
# carry both.

Assigning a stream over the API

PATCH /api/domains/{id} takes the four fields together. Every one is optional, and an omitted field is left alone.

curl -X PATCH https://api.sendly.now/api/domains/$DOMAIN_ID \
  -H "Authorization: Bearer $SENDLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": "MARKETING",
    "streamDefault": true,
    "defaultFromAddress": "news@news.example.com",
    "defaultFromName": "Acme News"
  }'

The sender name recipients see

The inbox shows a name beside the address: Acme News <news@news.example.com>. Sendly picks that name in this order:

1. The send's own name: from: { "email": ..., "name": ... } or name on POST /api/v1/emails.
2. The from-name on the template the send uses.
3. The defaultFromName on the identity the address is on.
4. The project name.

defaultFromName belongs to the identity, not to a stream. It applies to every send leaving on that host, and unassigning the identity keeps it. Set it once and every send that doesn't name itself goes out under your brand name instead of your project's internal name.

It needs the domains:write scope, the same as adding or removing a domain.

The name has a picture to go with it: every identity also has a sender logo that mailboxes supporting BIMI show beside the name, and its default is titled with this name.

Verification

Each identity verifies on its own, because each is a separate SES identity. Adding news.example.com gives you a separate DKIM record set to publish, and the domain page shows its DKIM, SPF, DMARC and MAIL FROM status independently of the root's.

Until an identity verifies, no send falls back to it. An unverified default is skipped rather than used, so an assignment made ahead of DNS never puts mail out unsigned.

See verifying domains for the record set, and guided DNS setup to have them published for you.

Subdomains and your account standing

Adding identities does not change your sending limits. Sendly counts registrable domains, not domain rows, when it works out how much of your domain setup you have proved — three identities under example.com count as the one domain they are. Splitting your streams is a deliverability decision, and it is not a way to buy volume.