Browse the docs

Email

Send one email at a time from your own system: an order confirmation, a receipt, a password reset, or a marketing email to somebody who agreed to receive it. Every rule of an email campaign applies: your verified From addresses, consent, the suppression list, the footer with your postal address and an unsubscribe link, your daily limit and your wallet.

Base address: https://app.ezreach.in/api/v1

POST/api/v1/email/messages

Send an email

Permission:email:sendIdempotency-KeyCounts as a send

Sends ONE email to ONE address and answers once Amazon SES has accepted it (status sent). Delivery, bounces and spam complaints arrive later from Amazon: follow them with GET /email/messages/{id}. Email must be switched on for your workspace, with a verified sending domain (or your EzReach address) and your postal address filled in under Email > Footer & tracking.

Body

  • torequired

    string

    One email address (no name, no list). Send one request per person.

  • fromrequired

    string

    One of your From addresses: a sender on your verified domain or your EzReach address (e.g. orders@mail.example.com), or that sender's id. Any other address is refused.

  • fromName

    string

    The name people see, instead of the sender's own (one line, at most 100 characters, no < > " @ \).

  • subjectrequired

    string

    One line, at most 300 characters. Line breaks and other control characters are refused.

  • html

    string

    The body as HTML (at most 262,144 characters). It is cleaned like an HTML email template: scripts, forms and unsafe links are removed.

  • text

    string

    The plain-text body (at most 65,536 characters). Without html, the email is built from this text. Send html, text or both.

  • replyTo

    string

    One address replies go to (reply_to is accepted too). Default: the sender's own reply address. It must be an inbox you read: never an address on the platform's own domains.

  • kindrequired

    "transactional" | "marketing"

    transactional: a message the person needs because of something they did with you (receipts, order or booking confirmations, password resets, account notices). marketing: offers, news, anything promotional.

  • tags

    Record<string, string>

    Up to 10 names (letters, digits, - and _) with one-line values (at most 256 characters), returned with the email. Not shown to the person.

Request

curl -X POST "https://app.ezreach.in/api/v1/email/messages" \
  -H "Authorization: Bearer $EZREACH_API_KEY" \
  -H "Idempotency-Key: order-A-1042-receipt" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "ananya@example.com",
  "from": "orders@mail.example.com",
  "subject": "Your order A-1042 is confirmed",
  "html": "<h1>Thank you, Ananya!</h1><p>Your order <strong>A-1042</strong> is confirmed and will ship tomorrow.</p>",
  "text": "Thank you, Ananya! Your order A-1042 is confirmed and will ship tomorrow.",
  "kind": "transactional",
  "tags": {
    "order": "A-1042"
  }
}'

Response

200 OK
{
  "data": {
    "id": "cm4em41lm3ss4g30001k2l3m4n",
    "to": "ananya@example.com",
    "from": "orders@mail.example.com",
    "kind": "transactional",
    "status": "sent",
    "tags": {
      "order": "A-1042"
    },
    "errorCode": null,
    "errorMessage": null,
    "bounceType": null,
    "bounceSubType": null,
    "timestamps": {
      "createdAt": "2026-09-16T10:30:00.000Z",
      "sentAt": "2026-09-16T10:30:00.380Z",
      "deliveredAt": null,
      "bouncedAt": null,
      "complainedAt": null,
      "failedAt": null
    }
  }
}
More request examples(2)
Marketing email (the address must have recorded consent)
{
  "to": "ananya@example.com",
  "from": "news@mail.example.com",
  "fromName": "Acme Store",
  "subject": "New arrivals this week",
  "html": "<h2>New arrivals</h2><p>See what just landed in the store.</p><p><a href=\"https://shop.example.com/new\">Shop new arrivals</a></p>",
  "replyTo": "hello@example.com",
  "kind": "marketing"
}
Text only
{
  "to": "ananya@example.com",
  "from": "orders@mail.example.com",
  "subject": "Your password reset code",
  "text": "Your code is 482913. It expires in 10 minutes.",
  "kind": "transactional"
}

Errors

  • 402INSUFFICIENT_BALANCE

    Your wallet does not cover this email. Nothing was sent. Top up and send it again.

  • 403EMAIL_NOT_ALLOWED

    Email is not switched on for your workspace yet.

  • 403EMAIL_ON_HOLD

    Sending is on hold for your workspace (for example a high bounce or spam rate). Only the platform team lifts it.

  • 403BRAND_SUSPENDED

    Your workspace is suspended: nothing is sent.

  • 403NO_PRICE

    No email price is set for your workspace yet (or NO_EMAIL_RATE: the platform has not set what an email costs). Ask the platform team.

  • 422FROM_NOT_ALLOWED

    from is not one of your From addresses (or your EzReach address was switched off or let go).

  • 422DOMAIN_NOT_VERIFIED

    The sender's domain is not verified (yet), or EzReach addresses are not ready.

  • 422SENDER_DISABLED

    That From address is switched off.

  • 422REPLY_TO_NOT_ALLOWED

    replyTo is an address on the platform's own domains (or, for an EzReach address, the sending address itself). Replies must go to an inbox you read.

  • 422NO_POSTAL_ADDRESS

    Add your postal address under Email > Footer & tracking: every email carries it.

  • 422CONTENT_INVALID

    Nothing is left of the content after cleaning, or a link holds a {{ }} field. details.issues lists what is wrong.

  • 422NO_CONSENT

    Marketing only: nobody recorded that this address agreed to receive email from you (POST /email/consent).

  • 422UNSUBSCRIBED

    Marketing only: the person unsubscribed from your marketing email. A transactional email still goes to them.

  • 422SUPPRESSED_BOUNCE

    Emails to this address bounced for good. Also SUPPRESSED_COMPLAINT (marked as spam), SUPPRESSED_PLATFORM (Amazon's list), SUPPRESSED_MANUAL (your own list), INVALID_ADDRESS, ERASED and BLOCKED_CONTACT (any contact with this address is blocked). Refused for both kinds.

  • 422FREQUENCY_CAP

    Marketing only: this address already got the most marketing emails you allow per 7 days (campaigns and the API together; Email > Footer & tracking).

  • 429ADDRESS_LIMIT

    Transactional only: this address already got 5 transactional emails from you in the last 24 hours, or 20 in 7 days. Nothing was sent; Retry-After says when it frees up.

  • 422SEND_FAILED

    Amazon refused this email (details.retryable false, details.email holds the record).

  • 429EMAIL_DAILY_LIMIT

    Your workspace reached its daily email limit (campaigns and the API share it). Retry-After says when it frees up (midnight India time).

  • 429RATE_LIMITED

    More than 600 sends a minute with this key (or 1,800 across your workspace's keys), more emails a second than your workspace's pace, or Amazon was busy. Nothing was sent; wait for Retry-After.

  • 502SEND_OUTCOME_UNKNOWN

    Amazon did not answer clearly, so whether the email went out is unknown. details.retryable is false: do not send it again. GET /email/messages/{id} shows the record; if the email did go out, Amazon's delivery report updates it.

  • 503EMAIL_UNAVAILABLE

    Email sending has a problem on the platform's side (not set up, the panel has no permanent address, Amazon unreachable or its daily allowance used up). Nothing was sent (details.retryable true).

  • transactional means a message the person needs because of something they did with you: a receipt, an order or booking confirmation, a password reset, an account notice. Consent is not needed, and somebody who unsubscribed from your marketing still gets it; it is refused for an address that bounced for good, marked your email as spam, is on Amazon's or your own block list, was erased, or belongs to a blocked contact.
  • Each address gets at most 5 transactional emails a day and 20 a week from your workspace through the API (429 ADDRESS_LIMIT). The platform watches the bounce and spam rates of your transactional email on their own, and how many go to addresses you have no contact or consent record for. Sending offers as transactional breaks the platform's terms and can get email switched off for your workspace.
  • marketing needs the address's recorded email consent (POST /email/consent or the panel), is refused for every suppression including an unsubscribe, and counts towards your per-address weekly limit.
  • Both kinds carry your footer: your business name, postal address and an unsubscribe link, plus the one-click List-Unsubscribe headers mailboxes use. A transactional email's footer says it is a service message. Unsubscribing stops your marketing email to that address.
  • The content is sent as given after cleaning: no merge fields and no open or click tracking.
  • Each email costs your workspace's email price (the same as a campaign email). The price is held in your wallet before the email is sent (402 when the wallet does not cover it), taken from the hold once Amazon accepts it, and the hold goes back if it is not sent.
  • Send an Idempotency-Key header: a repeat after a timeout on your side then gets the first answer back instead of sending a second email.
GET/api/v1/email/messages/{id}

Get email status

Permission:email:read

Returns an email sent through the API with its current status. Amazon's delivery reports keep it up to date.

Path parameters

  • idrequired

    string

    The email id returned when sending.

Request

curl "https://app.ezreach.in/api/v1/email/messages/cm4em41lm3ss4g30001k2l3m4n" \
  -H "Authorization: Bearer $EZREACH_API_KEY"

Response

200 OK
{
  "data": {
    "id": "cm4em41lm3ss4g30001k2l3m4n",
    "to": "ananya@example.com",
    "from": "orders@mail.example.com",
    "kind": "transactional",
    "status": "delivered",
    "tags": {
      "order": "A-1042"
    },
    "errorCode": null,
    "errorMessage": null,
    "bounceType": null,
    "bounceSubType": null,
    "timestamps": {
      "createdAt": "2026-09-16T10:30:00.000Z",
      "sentAt": "2026-09-16T10:30:00.380Z",
      "deliveredAt": "2026-09-16T10:30:04.000Z",
      "bouncedAt": null,
      "complainedAt": null,
      "failedAt": null
    }
  }
}

Errors

  • 404NOT_FOUND

    No email with this id was sent through the API from this workspace.

  • status is queued (being sent), sent (Amazon accepted it), delivered (the receiving server took it), bounced, complained (the person marked it as spam) or failed (not sent; errorCode and errorMessage say why).
  • An email can move from delivered to bounced or complained later. bounceType (Permanent, Transient, Undetermined) and bounceSubType come from Amazon.
  • errorCode SEND_OUTCOME_UNKNOWN: Amazon never answered clearly. The email stays failed unless Amazon's report shows it went out; never send it again automatically.
  • to is null once the person's data was erased.