Sender Identities

What is a Sender Identity?

A sender identity is a verified email address or domain that you can use to send emails. Verification proves you own or control the sending address, which is required for email authentication.

Types of Verification

Domain Verification (Recommended)

Verify an entire domain to send from any address at that domain:

• hello@yourdomain.com
• support@yourdomain.com
• noreply@yourdomain.com

Benefits:

• Send from any address at the domain
• Better deliverability with proper authentication
• Professional appearance

Single Sender Verification

Verify individual email addresses when you can't verify the full domain:

• Quick setup for testing
• No DNS access required
• Limited to verified address only

Domain Verification Process

Step 1: Add Your Domain

1. Go to Senders in your email server
2. Click Add Domain
3. Enter your domain (e.g., yourdomain.com)

Step 2: Add DNS Records

You'll need to add three types of DNS records:

SPF Record

SPF (Sender Policy Framework) authorizes Transactional to send on your behalf:

Type: TXT
Host: @ (root domain)
Value: v=spf1 include:spf.usetransactional.com ~all

If you have an existing SPF record, add include:spf.usetransactional.com to it.

DKIM Record

DKIM (DomainKeys Identified Mail) adds a digital signature to your emails:

Type: TXT
Host: transactional._domainkey
Value: [provided in dashboard]

DMARC Record (Recommended)

DMARC (Domain-based Message Authentication) sets policy for failed authentication:

Type: TXT
Host: _dmarc
Value: v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com

Step 3: Verify Records

1. Click Verify in the dashboard
2. We'll check your DNS records
3. Verification may take up to 48 hours for DNS propagation

Verification Status

Signing Domain Isolation

For advanced users who want to isolate their transactional email reputation from their main domain, you can configure a signing domain that differs from your sender address.

What is Signing Domain Isolation?

When you send emails, DKIM signs them with a cryptographic key associated with a domain. By default, this is the domain in your sender email address. With signing domain isolation, you can sign emails with a subdomain instead.

Example:

• Sender email: hello@yourdomain.com
• Signing domain: mail.yourdomain.com

The email appears to come from hello@yourdomain.com, but DKIM is signed with mail.yourdomain.com.

Benefits

1. Reputation Isolation - If transactional emails cause deliverability issues, your main domain reputation remains protected
2. Subdomain Management - Separate DKIM keys for different email types
3. DMARC Compliance - Both domains share the same organizational domain, ensuring DMARC passes

Requirements

The signing domain must share the same organizational domain as the sender email for DMARC alignment:

Setting Up Signing Domain Isolation

1. Add the signing domain - Go to Senders and add your subdomain (e.g., mail.yourdomain.com)
2. Verify DNS records - Add the required DNS records for the subdomain
3. Create sender with signing domain - When adding a sender, expand "Advanced Options" and select the signing domain

// Via API - Create sender with signing domain
await fetch('/senders', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'hello@yourdomain.com',
    name: 'Hello',
    signingDomainId: 123, // ID of mail.yourdomain.com
  }),
});

Sender Display Names

Configure how your sender appears in email clients:

await client.emails.send({
  from: 'support@yourdomain.com',
  fromName: 'Acme Support', // Display name
  to: 'user@example.com',
  subject: 'Your support ticket',
  html: ticketTemplate,
});

Recipients see: Acme Support <support@yourdomain.com>

Reply-To Addresses

Set a different reply-to address than the from address:

await client.emails.send({
  from: 'noreply@yourdomain.com',
  replyTo: 'support@yourdomain.com',
  to: 'user@example.com',
  subject: 'Your order confirmation',
  html: orderTemplate,
});

Managing Senders via API

List Senders

curl -X GET "https://api.usetransactional.com/senders" \
  -H "X-API-Key: your-api-key"

Response includes signingDomainId and signingDomain for senders using domain isolation:

{
  "totalCount": 2,
  "senders": [
    {
      "id": 1,
      "email": "hello@example.com",
      "name": "Hello",
      "status": "VERIFIED",
      "isDefault": true,
      "signingDomainId": null,
      "signingDomain": null
    },
    {
      "id": 2,
      "email": "support@example.com",
      "name": "Support",
      "status": "VERIFIED",
      "isDefault": false,
      "signingDomainId": 5,
      "signingDomain": {
        "id": 5,
        "name": "mail.example.com",
        "status": "VERIFIED"
      }
    }
  ]
}

Create Sender

curl -X POST "https://api.usetransactional.com/senders" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "notifications@example.com",
    "name": "Notifications",
    "replyTo": "support@example.com",
    "signingDomainId": 5
  }'

Update Sender

curl -X PATCH "https://api.usetransactional.com/senders/1" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "signingDomainId": 5
  }'

To remove a signing domain, set it to null:

curl -X PATCH "https://api.usetransactional.com/senders/1" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "signingDomainId": null
  }'

Delete Sender

curl -X DELETE "https://api.usetransactional.com/senders/1" \
  -H "X-API-Key: your-api-key"

Best Practices

Use Recognizable Addresses

• hello@company.com - Friendly, approachable
• support@company.com - Clear purpose
• notifications@company.com - Automated messages

Avoid Generic Addresses

• noreply@... - Discourages engagement
• donotreply@... - Unfriendly
• system@... - Impersonal

Consistent From Addresses

Use consistent sender addresses for each email type:

When to Use Signing Domain Isolation

Consider signing domain isolation when:

• You send high volumes of transactional email
• You want to protect your main domain's reputation
• You're starting with a new domain and want to build reputation separately
• You have strict deliverability requirements

Troubleshooting

DNS Records Not Found

• Wait up to 48 hours for DNS propagation
• Verify records with a DNS lookup tool
• Check for typos in record values
• Ensure records are on the correct domain

SPF Failures

• Check if you have multiple SPF records (only one allowed)
• Verify the include statement is correct
• Check for SPF record length limits

DKIM Failures

• Ensure the record is on the correct subdomain
• Check for line breaks or extra spaces in the value
• Verify the full record value was copied

DMARC Alignment Issues

If using signing domain isolation and DMARC is failing:

• Verify both domains share the same organizational domain
• Check that the signing domain's DKIM record is properly configured
• Ensure DMARC policy allows subdomain alignment

Next Steps

• API Keys - Set up authentication for sending
• Best Practices - Improve deliverability
• Tracking - Configure open and click tracking