Skip to content
mailcatchrmailcatchr

Outbound sending

Sending covers the other half of email testing: exercising the code that receives mail, checking a reply flow, or driving a mail client with realistic traffic.

Before the first send

Section titled “Before the first send”
  1. Business plan. Outbound is off on the Free plan.
  2. Enable it on the mailbox under Settings → Outbound.
  3. A verified sending identity. The from address must use a domain verified in the workspace. Ask support to verify yours.
  4. Recipient allowlist. Each mailbox keeps a list of addresses and *.domain patterns it may send to. Anything else is refused with 422. This is what stops a test suite emailing real customers.
  5. Wallet balance. Sends cost $0.50 per 1,000 emails, debited from the prepaid wallet under Workspace settings → Billing.

Sending

Section titled “Sending”
POST /v1/mailboxes/{mailboxId}/send
const result = await mc.send(mailboxId, {
  from: "noreply@acme.send.mailcatchr.com",
  to: "qa@acme-ci.mailcatchr.com",
  subject: "Welcome",
  textBody: "Hi there",
});
// result.status === "queued"; result.messageId is the message's id in the mailbox

The API answers 202 as soon as the send is queued. Delivery is asynchronous; bounces and complaints arrive as mail notifications. Send an Idempotency-Key so a retried request does not send twice.

Suppression list

Section titled “Suppression list”

Addresses that bounced or complained are added to a workspace-wide suppression list and refused on later sends with 422 suppressed_recipients. List and clear entries over the API:

GET    /v1/workspaces/{workspaceId}/suppression
DELETE /v1/workspaces/{workspaceId}/suppression/{id}

Errors

Section titled “Errors”

See Errors for the full list. The ones a new setup hits first are 403 outbound_disabled, 422 invalid_from_domain and 402 insufficient_funds.