Skip to content

Glossary

Glossary

42 email and agent-sending terms on one page: each defined in a sentence, then how it decides a send.

Appeal

Appeal: A request for a person to review a pause or a sandbox. Filing it does not resume sending.

POST /trust/appeal files the review. Read GET /trust/standing first so the request names the reason. Filing the appeal does not move standing back to ok, and it does not lift a sandbox.

A person decides it, in 24 to 72 hours. Filing also opens a support ticket you can follow in the console under Support. Retrying the send while the account is paused returns the same refusal.

Related: Standing, Sandbox

Approval queue

Approval queue: Sends held for a person to approve or reject. Approving sends the held message.

A held send is recorded, not discarded. request_approval asks for that hold. There is no separate REST call that asks. A person approves or rejects it in the console under Agents, and approving sends it.

The key that asked cannot approve itself. A hold lasts 24 hours unless the send named an earlier time. The refusal is approval_required. See Loop detection for the repeat that files one on its own.

Related: Loop detection, Human action required

Batch

Batch: Several different messages in one request. One item can fail on its own.

POST /emails/batch takes up to 500 different messages. Without an extra header, each item is accepted or refused on its own: one bad address does not drop the rest.

Each item still faces the rate ceiling, the budget, suppression, and the idempotency key rules. A batch is not a list of people you have not met.

Related: Idempotency key, Rate ceiling

Block bounce

Block bounce: A refusal on reputation or content. The address itself is not the cause.

A block bounce means the receiver refused the message on reputation or content. The address can be real. Treating it as a dead address sends you to clean a list that is fine.

This is the class that ends in a blocklist if it continues. Cut volume on the domain and read the complaint rate. Recipients who never asked for the mail are the usual cause.

Related: Policy bounce, Complaint rate

Budget period

Budget period: The window a key's send budget refills on: hourly, daily or monthly.

budget_per_period is how many recipients a key may accept inside one budget period. A new key uses monthly. The same count on a shorter window allows more mail, because the number refills sooner, and a key cannot make that change.

PATCH /limits/keys/{id} takes period as hourly, daily or monthly. See Plan inclusion for the account cap that sits above the key.

Related: Rate ceiling, Plan inclusion

Complaint rate

Complaint rate: The share of delivered mail that recipients mark as spam, judged by the ladder.

A complaint is a recipient marking the message as spam. The rate is complaints over mail that was delivered, inside the trust window of 7 days.

The enforcement ladder warns at 0.05% and pauses at 0.08%. A feedback loop report is one way a complaint arrives.

Related: Enforcement ladder, Feedback loop

Dead letter

Dead letter: A webhook delivery kept after the retries are used up, so it can be replayed.

A delivery that does not succeed is retried 10 times, on the schedule in the webhooks guide. After the last failure it is dead-lettered rather than dropped.

The console shows every attempt. Replay the dead letter once the endpoint is fixed. An endpoint that keeps failing is disabled and the account is notified. Verification of each delivery is webhook signing.

Related: Webhook signing, Signature tolerance

DKIM alignment

DKIM alignment: The signing domain and the From domain match, or they share one organisation domain.

DKIM alignment holds when the domain in the signature and the domain in From are the same, or they share one organisation domain. The signature is the key published at as1._domainkey on your sending domain.

Publish every string of that record. A key cut off at the editor's line length never resolves, and an unresolved key cannot align. DMARC alignment can pass on this result alone.

Related: SPF alignment, DMARC alignment

DMARC alignment

DMARC alignment: A pass when either DKIM alignment or SPF alignment passes for the From domain.

DMARC asks a receiver to check DKIM alignment and SPF alignment, and it passes when either one passes. The TXT at _dmarc on your sending domain is recommended. A domain verifies and sends without it.

Start the policy at p=none with a reporting address, read the reports, then tighten the policy. The record does not block verification.

Related: DKIM alignment, SPF alignment

Enforcement ladder

Enforcement ladder: Warn, then pause, on bounce rate and complaint rate. One step per check.

Bounce rate warns at 2% and pauses at 4%. Complaint rate warns at 0.05% and pauses at 0.08%. The ladder moves one step per check: ok to warning, warning to paused. It does not jump from ok to paused in one pass.

No step is taken until 100 delivered-or-bounced sends in the 7-day window. Recovery needs that whole window under the warn line. The result is the account's standing.

Related: Standing, Complaint rate

Feedback loop

Feedback loop: A mailbox provider's notice that a recipient marked the message as spam.

A feedback loop, often shortened FBL, is a mailbox provider's report that someone marked the message as spam. We count it as a complaint and the address joins suppression.

It is not a bounce. The complaint rate is where the ladder reads the count. The report names the recipient; it does not name a new audience to mail.

Related: Complaint rate, Suppression

Fix field

Fix field: The sentence on every refusal that says what to do next and which call does it.

Every refusal body carries code, message, fix and docs_url. fix is the instruction: which call to make, or who has to decide. Quote it. Do not paraphrase it into a different action.

When the refusal is retryable it also carries retry_after_seconds. When it is not, that field is absent, and the fix is the whole answer. The catalogue is /docs/errors.

Related: retry_after_seconds, Idempotency key

Full access

Full access: A key that can manage the account as well as send. It still cannot raise its own budget.

permission full_access on POST /api-keys is the key that can change domains, webhooks, contacts, templates, segments and topics, and can send. It is the key you keep. It is not the key you hand to an agent for one job.

It still cannot raise its own budget. That is human action required on every key. The narrower grant is sending access. Scopes on a connected assistant are an MCP scope, not this permission.

Related: Sending access, MCP scope

Hard bounce

Hard bounce: A permanent bounce: the address does not exist, and it is suppressed.

A hard bounce means the receiving server says the address does not exist. It is permanent. The address is placed on the suppression list, and a later send to it is refused.

Remove the address where you store it, so the same list does not keep producing the bounce. The class list on /docs is the same four classes, under Bounce classes.

Related: Suppression, Soft bounce

Human action required

Human action required: A change only a person can make. A key cannot raise its own limits.

A key may lower its own limits. Raising budget_per_period, shortening the budget period so the same count refills more often, or clearing rate_ceiling_per_minute is a person's decision. The refusal is human_action_required.

The fix is to ask whoever runs the account to do it in the console. Retrying with the same key fails the same way. Resuming a kill switch is the same kind of decision.

Related: Budget period, Kill switch

Idempotency key

Idempotency key: The caller-chosen key that makes a retry of the same request return the first result.

Send Idempotency-Key on a mutating call. A retry with the same key and the same body returns the first result and does not send again. The key is kept for 7 days. Derive it from the thing being done, not from the clock.

The same key with a different body is idempotency_payload_mismatch. The fix field says to reuse the body or to send a new key. A new send needs a new key.

Related: Fix field, retry_after_seconds

Inbound thread

Inbound thread: Messages grouped by their ids and reply headers. Receiving is open: one MX record on a verified domain.

Receiving is open: turn it on for a verified domain, publish the MX record its page shows, and mail to that domain arrives on your account.

A thread is the group of messages tied by Message-ID, In-Reply-To and References. A reply to mail that arrived in some other inbox still threads: copy those headers onto POST /emails. See MCP scope for inbound:read, the scope that reads it.

Related: Sending domain, MCP scope

Kill switch

Kill switch: A pause that stops a key, or every key, from sending on the next request.

POST /limits/keys/{id}/kill pauses one key. POST /limits/kill-all pauses every key on the account. Both take effect on the next request. The paused key cannot resume itself.

A person signed in to the console resumes it. The refusal while it is paused is kill_switch_active. Read Standing when the pause came from the trust ladder instead.

Related: Standing, Human action required

List-Unsubscribe

List-Unsubscribe: The header a mailbox shows as unsubscribe. Topic sends and broadcasts carry one.

List-Unsubscribe is one or two links in angle brackets, an https link and a mailto link. List-Unsubscribe-Post is the one-click companion, and only next to an https link. You can set both on a send whose From is a domain you have verified here. If that domain is not verified, the refusal is domain_not_verified and the message names the header.

A send with a topic_id, and every broadcast, already carries a pair that records the click as a topic opt-out or a suppression. Do not add a second pair that points somewhere else on those sends.

Related: Topic, Suppression

Loop detection

Loop detection: A hold on a near-identical repeat, and on a send into an inbox a window has collapsed onto.

Before every send the guard reads this key's mail from the last 60 minutes. A candidate that would be the 4th near-identical message to the same recipient is held. Near-identical means subject and body similarity of at least 85%.

On a key set to full, and on a marketing send from a key with no setting, it also holds the next send to an inbox that a window of at least 20 sends has collapsed onto, once that window has fewer than 3 effective recipients. Mail to anyone else still sends. A new key is repetition-only. The hold is an approval queue entry, answered as approval_required.

Related: Approval queue, Idempotency key

MCP scope

MCP scope: A permission granted to a connected assistant. Sending spends the budget on that connection.

A connected assistant holds scopes, not your password. emails:send delivers mail from your verified domains and spends the budget. emails:read reads mail you sent. Scopes for domains, webhooks, limits, contacts, templates, segments and topics are separate, and each is what the consent screen names.

inbound:read reads mail that arrived at your domains, with its attachments and the conversation it belongs to; held mail stays out of it until a person releases it. A sending access key does not receive that scope. Full access is the broader key, and it is still not a grant to mail strangers.

Related: Sending access, Full access

Overage

Overage: Emails past the inclusion, only when you have turned them on and set a ceiling.

Sends stop when the plan inclusion is spent. Nothing is auto-charged. Overage starts only after you turn it on and set a ceiling, in multiples of the inclusion up to 10 times.

A key's own budget period still applies while overage is on. Overage does not raise a key, and it does not mail anyone the key was not already going to mail.

Related: Plan inclusion, Budget period

Plan inclusion

Plan inclusion: The emails included in the plan for the month. A key budget cannot exceed it.

Every account starts on Free: 5,000 emails a month, 170 a day, 3 verified domain. A key's budget period count cannot be null and cannot be higher than that monthly inclusion. The refusal is key_budget_exceeds_plan.

Spending the inclusion refuses the next send with plan_limit_reached. Free also stops at the daily number. Paid plans do not add a daily cap of their own. Overage is off until you turn it on with a ceiling.

Related: Budget period, Overage

Policy bounce

Policy bounce: The address is real. This message was refused for size, an attachment, or suppression.

A policy bounce means the address is real and the receiver would take mail from you, but not this message. The cause is size, an attachment type, or our suppression list.

Shrink the message or drop the attachment and send again. A suppression reason is an address you can inspect, not a dead mailbox. It is not a hard bounce.

Related: Hard bounce, Suppression

Preflight

Preflight: A check that reports what a send would do, without sending it or recording a hold.

POST /emails/preflight runs the same gates as a send and does not accept the message. It does not charge the budget and it does not file an approval. Use it, or a simulator address, before a sending domain is verified.

The reply names the gate that would refuse the real send. A preflight that passes is not a delivery.

Related: Simulator address, Sending domain

Rate ceiling

Rate ceiling: How many recipients one key may accept in a single minute.

rate_ceiling_per_minute is separate from the budget period. A new key starts at 600 a minute. PATCH /limits/keys/{id} can lower it. Null does not clear it for a key: clearing a ceiling is a raise, and a raise is a person's decision.

Past the ceiling the send is refused with rate_ceiling_exceeded. That refusal carries retry_after_seconds.

Related: Budget period, retry_after_seconds

retry_after_seconds

retry_after_seconds: The wait, in seconds, on a refusal that waiting can cure. Absent when waiting cannot.

A retryable refusal includes retry_after_seconds. Wait that many seconds and send the same request again. A rate ceiling refusal is one of these.

A refusal that waiting cannot cure omits the field. Do not invent a wait for it. Read the fix field: that sentence says what to change.

Related: Fix field, Rate ceiling

Return path

Return path: The MX and TXT on your domain that receive bounces and keep the envelope aligned.

A new sending domain publishes two records on a subdomain, send. unless you pass another label. The MX receives bounces. The TXT is the SPF record that keeps SPF alignment.

Both are required before the envelope moves to a VERP address on that host. Until they resolve, the envelope sender stays the From address. Neither record is a shared hostname of ours.

Related: VERP, SPF alignment

Sandbox

Sandbox: An account limited to sending to its own verified domains until a person reviews it.

A sandboxed account may send only to a domain it has verified. The refusal is account_sandboxed. Verify the recipient domain, or file an appeal for a person to review the account.

A simulator address is how you exercise the send path before a domain of yours is verified. The sandbox is not a second product: it is this limit on who may be mailed.

Related: Sending domain, Appeal

Scheduled send

Scheduled send: A message accepted now and delivered at a later time you set. Counted at accept.

scheduled_at accepts the message now and sends it at that time. The furthest time is 30 days out. The recipients count against the budget period and the plan inclusion at accept, not at send.

Cancelling it while it is still scheduled gives that count back. A past time within a short tolerance sends now. Older than that, the call is refused. Use a new idempotency key when the scheduled message is a different send.

Related: Budget period, Idempotency key

Sending access

Sending access: A key that sends and reads what it sent. It cannot edit the account.

permission sending_access can send and can read the messages that key sent. It cannot mint keys, edit domains, or change contacts, suppressions, templates or segments. Hand this to an agent.

It does not include inbound:read. A sending key never reads what arrived; that read belongs to a full-access key or an assistant granted inbound:read. The management key is full access.

Related: Full access, MCP scope

Sending domain

Sending domain: A domain you verify, then send from. An unverified From is refused.

POST /domains adds the domain. Publish the records from GET /domains/{id}, then POST /domains/{id}/verify. DKIM and both return path records are what a new domain must resolve. The SPF and DMARC records are recommended and do not block sending.

The From address has to be on a verified domain. DKIM alignment is the signature on that same domain. Free includes 3 verified domain.

Related: DKIM alignment, Return path

Signature tolerance

Signature tolerance: How old a webhook timestamp may be before the delivery is rejected as a replay.

Reject a webhook timestamp more than 5 minutes from now. The webhook signing check is the signature and this window together. A correct signature on an old timestamp is still a replay.

The secret can be rotated. A previous secret stays valid for 24 hours so a delivery already in flight still verifies. After the retries, the delivery is a dead letter.

Related: Webhook signing, Dead letter

Simulator address

Simulator address: An address that accepts a send, costs nothing, and delivers to nobody.

Send to delivered@simulator.agentisend.com, bounced@simulator.agentisend.com or complained@simulator.agentisend.com while a sending domain is still verifying. simulated on the reply is true only when every recipient is one of these addresses. One recipient anywhere else and the send is delivered and counted.

A bounce from bounced@simulator.agentisend.com does not join the suppression list. The same address on a real domain does.

Related: Sending domain, Suppression

Soft bounce

Soft bounce: A temporary refusal. The message can be tried again later.

A soft bounce is temporary. The mailbox is full, the receiver greylisted the message, or the receiver was briefly unavailable. Nothing is removed from your list for one of these.

We retry it. It becomes your problem when the same address keeps soft-bouncing for days, and it is then treated as a hard bounce.

Related: Hard bounce, Block bounce

SPF alignment

SPF alignment: The envelope domain and the From domain match, or they share one organisation domain.

SPF alignment holds when the domain of the envelope sender and the domain in From are the same, or they share one organisation domain. After the return path resolves, the envelope is on a subdomain of your domain, which is what makes this true.

The SPF record on the sending name itself is recommended cover. Merge it into an existing record. A second SPF record does not add up; receivers read one.

Related: DKIM alignment, Return path

Standing

Standing: The trust state for transactional mail and for marketing mail, published for the account.

GET /trust/standing returns the state the ladder last wrote. The states it enforces are ok, warning and paused. A legacy throttled row is re-evaluated onto that ladder; the ladder does not enter throttled.

Marketing and transactional mail are judged apart. A marketing pause refuses marketing and leaves transactional mail sending. The refusal on a paused stream is trust_paused. File an appeal from the reasons that call names.

Related: Enforcement ladder, Appeal

Stream

Stream: Transactional or marketing. The ladder can pause one and leave the other sending.

A send is transactional unless you set it to marketing. Receipts, sign-in codes and support replies are transactional. An announcement to existing customers is marketing, and it carries the unsubscribe header.

Standing is kept per stream. A high complaint rate on marketing pauses marketing. Transactional mail on that account still sends. A key budget applies to both.

Related: Standing, Complaint rate

Suppression

Suppression: An address we will not mail. A later send to it is refused.

A suppressed address is refused with suppressed_recipient and is not delivered. A hard bounce, a complaint, and an unsubscribe each add one. GET /suppressions lists them. Removing one is a separate call, for an address you have a reason to mail again.

A topic opt-out blocks that topic and does not have to block every message. See Topic. A simulator bounce does not join this list.

Related: Hard bounce, Topic

Topic

Topic: A named kind of mail. A contact who opts out of it is skipped on sends of that kind.

Create a topic, then send with topic_id. A contact who opted out of that topic is not mailed, and the event says so. Someone who opted out of everything is on the suppression list and is skipped too.

The List-Unsubscribe header on a topic send records that opt-out. A topic is not a way to add people. It is a way for people you already mail to say which kind they still want.

Related: List-Unsubscribe, Suppression

VERP

VERP: An envelope sender on your return-path host that names the message a bounce belongs to.

VERP is the envelope sender we use once your return path records resolve. It is an address on send. of your domain (or the label you chose) that names the message, so a bounce comes back to that send rather than to a shared host.

Until both return-path records resolve, the envelope sender stays the From address. The return-path TXT is what keeps SPF alignment once the envelope moves.

Related: Return path, SPF alignment

Webhook signing

Webhook signing: A timestamp and a signature over the raw body, checked before the payload is parsed.

Each delivery signs timestamp.body with the endpoint's signing secret. Compare in constant time, and reject a timestamp outside the signature tolerance. Without the timestamp check a captured delivery can be replayed at you for as long as you keep the secret.

Read the raw body. Parsing and writing the JSON again changes bytes, and the signature then fails at random. A dead end after the retries is a dead letter.

Related: Signature tolerance, Dead letter