Senders

A workspace can have one sender per send type, on top of the general default sender. This lets marketing, automated and transactional email go out from distinct addresses and domains, for example news@news.yourdomain.com for campaigns and hello@yourdomain.com for automations.

The three send types

Each type is either null (not configured) or an object with fromEmail, fromName and replyTo. fromEmail and fromName go together: a type is configured or it is not, and a type never borrows half of its sender from the general default.

The general default sender is the pair defaultFromEmail / defaultFromName on the workspace. It stays where it was: nothing was copied into the three types, and a type you never configured behaves exactly as before.

How a sender is chosen

For every send, Tratto takes the first value that exists:

A type that is not configured inherits the general default. It is never the reason a send is refused.

Marketing

A campaign created without fromEmail/fromName takes the marketing sender, or the general default if there is none. The sender is written on the campaign when it is created: changing the marketing sender later does not change campaigns that already exist. See Campaigns.

The test send of a template uses the same sender.

Automation

When you activate a flow, every send_email step without its own from gets the automation sender, or the general default if there is none. The sender is written on the step at activation and stays there, even if you later change the automation sender or the general one. Deactivating and activating the flow again does not change it, because the step now has its own from.

To change the sender of an existing flow: deactivate it, update its steps through the API removing from, fromName and replyTo from the sending step, then activate it again. The dashboard cannot do this today: the flow editor has no sender field. See Flows.

A step that inherits the automation sender also inherits its replyTo. A step with its own from keeps its own reply address, or none.

Transactional

from is optional on POST /v1/emails. When the request has no from, Tratto uses the transactional sender, or the general default if there is none. A request with from is sent from that address, exactly as before: the transactional sender does not replace it.

• The transactional sender is used as name and address together.
• The general default is used with its name if defaultFromName is set, or as the bare address if only defaultFromEmail is.
• With neither, the request fails with 422 VALIDATION_ERROR and the message No sender configured for this email., with a suggestion pointing to Settings → Senders.
• With a live key, the domain of the sender that was picked must be verified, as for an explicit from: otherwise 403 FORBIDDEN. Test keys skip this check. See Domains.

The replyTo of the transactional sender applies only when the request has no from and no replyTo of its own. A request with from gets no Reply-To from the transactional sender.

Omitting from in the SDKs requires @tratto/email 1.5.0 or newer, or tratto-email 2.0.0 or newer (from_). Over HTTP, from can be omitted with any client. See Send Email.

Rules

• fromEmail must be on a verified domain of the workspace. Otherwise the update fails with 403 FORBIDDEN and a message naming the domain, for example Domain 'news.yourdomain.com' is not verified for this tenant. See Domains.
• replyTo needs no verified domain. It is only checked to be a valid address: a malformed one is a 422.
• fromName is 1 to 100 characters.
• System emails sent by Tratto itself, such as team invitations, do not use these senders and cannot be configured.

Read the senders

GET /v1/workspace returns senders with all three keys, null where a type is not configured:

curl https://api.tratto.email/v1/workspace \
  -H "Authorization: Bearer tratto_live_..."

{
  "data": {
    "defaultFromEmail": "noreply@yourdomain.com",
    "defaultFromName": "Your Company",
    "senders": {
      "marketing": {
        "fromEmail": "news@news.yourdomain.com",
        "fromName": "Your Company News",
        "replyTo": "support@yourdomain.com"
      },
      "automation": null,
      "transactional": null
    }
  }
}

The response has more workspace fields: only the sender fields are shown here.

Set or clear a sender

PATCH /v1/workspace with senders updates only the types you send. The others keep their value. Sending null on a type clears it, and that type goes back to the general default. The API key needs the workspace:write permission (see Authentication).

cURL

# Set the marketing sender. automation and transactional are untouched.
curl -X PATCH https://api.tratto.email/v1/workspace \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "senders": {
      "marketing": {
        "fromEmail": "news@news.yourdomain.com",
        "fromName": "Your Company News",
        "replyTo": "support@yourdomain.com"
      }
    }
  }'

# Clear it: marketing goes back to the general default sender.
curl -X PATCH https://api.tratto.email/v1/workspace \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "senders": { "marketing": null } }'

Node.js (@tratto/email 1.2.0 or newer)

import { Tratto } from '@tratto/email';

const tratto = new Tratto(process.env.TRATTO_API_KEY!);

await tratto.workspace.update({
  senders: {
    marketing: {
      fromEmail: 'news@news.yourdomain.com',
      fromName: 'Your Company News',
      replyTo: 'support@yourdomain.com',
    },
  },
});

await tratto.workspace.update({ senders: { marketing: null } });

Python (tratto-email 1.2.0 or newer)

from tratto import Tratto

client = Tratto('tratto_live_...')

client.workspace.update({
    'senders': {
        'marketing': {
            'fromEmail': 'news@news.yourdomain.com',
            'fromName': 'Your Company News',
            'replyTo': 'support@yourdomain.com',
        }
    }
})

client.workspace.update({'senders': {'marketing': None}})

In the dashboard

Open Settings → Senders. The first row is the general sender, followed by one row per type. A type you have not configured says "Uses the general sender.". Each row, the general one included, has its own name, address and Save: saving the general sender does not change the per-type senders, and saving a type does not change the general one. The general sender can be replaced but not cleared. The address picker only offers domains that are verified for the workspace; without a verified domain the general sender is shown read-only. The sender fields are no longer in the Workspace tab.

The onboarding checklist counts the sender step as done as soon as the workspace has any sender, general or for one type.