Skip to content
iResendlyDocs

Emails

Send, batch, schedule, retrieve, reschedule and cancel emails.

6 endpoints

Sending endpoints work with full-access and sending-only keys. Reading, rescheduling and cancelling need a full-access key.

Send an email

POST/emailsSending keys allowed

Sends now, or at scheduled_at. Recipients on your suppression list are skipped (you get an email.suppressed event); if every recipient is suppressed the email is still created, with status failed.

Body
  • fromstringrequired

    Sender, e.g. Acme <hello@acme.com>. Its domain (or a parent domain) must be verified. Optional when template sets it.

  • tostring | string[]required

    Up to 50 addresses. Duplicates are removed.

  • subjectstringrequired

    Subject line. Optional when template sets it.

  • htmlstring

    HTML body, up to 2 MB. Send html, text or template.

  • textstring

    Plain-text body.

  • templateobject

    { id, variables }: a published template's id or alias. Can't be combined with html or text.

  • cc · bccstring | string[]

    Up to 50 each.

  • reply_tostring | string[]

    Reply-To addresses.

  • scheduled_atstring

    ISO 8601, or in 30 min, in 2 hours, in 1 day. Up to 30 days ahead; 10 seconds or less sends now.

  • attachmentsarray

    Up to 50 files, 40 MB in total: { filename, content } (base64) or { filename, path } (public URL), optional content_type, and content_id to show it inline. Executable files are refused. Not allowed with scheduled_at.

  • tagsarray

    Up to 10 { name, value } pairs (1–256 characters each), returned in webhooks.

  • headersobject

    Custom headers. From, To, Cc, Bcc, Subject, Reply-To, Message-ID, Date, MIME and DKIM headers can't be overridden.

POST/emails
curl -X POST 'https://api.iresendly.com/emails' \
  -H 'Authorization: Bearer irs_xxxxxxxxx' \
  -H 'Idempotency-Key: receipt-1042' \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": [
    "jane@example.com"
  ],
  "subject": "Your receipt",
  "html": "<p>Thanks for your order!</p>",
  "tags": [
    {
      "name": "category",
      "value": "receipt"
    }
  ]
}'
Response
{
  "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c"
}

Send a batch

POST/emails/batchSending keys allowed

Up to 100 emails in one request; the body is a JSON array of emails like the ones above, without attachments or scheduled_at. With the default x-batch-validation: strict, one invalid email fails the whole batch (the error names it, e.g. emails[3]: …). With permissive, valid emails are sent and the rest come back in errors with their index.

POST/emails/batch
curl -X POST 'https://api.iresendly.com/emails/batch' \
  -H 'Authorization: Bearer irs_xxxxxxxxx' \
  -H 'x-batch-validation: permissive' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "from": "Acme <hello@acme.com>",
    "to": [
      "omar@example.com"
    ],
    "subject": "Welcome, Omar",
    "html": "<p>Glad you'\''re here.</p>"
  },
  {
    "from": "Acme <hello@acme.com>",
    "to": [
      "lena@example.com"
    ],
    "subject": "Welcome, Lena",
    "html": "<p>Glad you'\''re here.</p>"
  }
]'
Response
{
  "data": [
    {
      "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c"
    },
    {
      "id": "ae2014de-c168-4c61-8267-70d2662a1ce1"
    }
  ]
}

Retrieve an email

GET/emails/{id}

One email with its latest event. Emails are kept for your plan's retention (1, 3 or 7 days), then return 404.

Path parameters
  • idstringrequired

    The email id.

GET/emails/{id}
curl -X GET 'https://api.iresendly.com/emails/{id}' \
  -H 'Authorization: Bearer irs_xxxxxxxxx'
Response
{
  "object": "email",
  "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
  "from": "Acme <hello@acme.com>",
  "to": [
    "jane@example.com"
  ],
  "cc": [],
  "bcc": [],
  "reply_to": [],
  "subject": "Your receipt",
  "status": "delivered",
  "last_event": "delivered",
  "created_at": "2026-11-07T10:00:00.000Z",
  "sent_at": "2026-11-07T10:00:01.000Z",
  "scheduled_at": null,
  "tags": [
    {
      "name": "category",
      "value": "receipt"
    }
  ],
  "attachments": [],
  "broadcast_id": null,
  "error": null
}

List emails

GET/emails

Newest first, within your plan's retention.

Query parameters
  • limitnumber

    Results per page, 1–100. Default 20.

  • afterstring

    Return results after this id (next page).

  • beforestring

    Return results before this id (previous page). Don't send with after.

GET/emails
curl -X GET 'https://api.iresendly.com/emails' \
  -H 'Authorization: Bearer irs_xxxxxxxxx'
Response
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "email",
      "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
      "subject": "Your receipt",
      "last_event": "delivered"
    }
  ]
}

Reschedule an email

PATCH/emails/{id}

Moves a scheduled email to a new time, in the future and within 30 days.

Path parameters
  • idstringrequired

    The email id.

Body
  • scheduled_atstringrequired

    The new time (ISO 8601 or in …).

PATCH/emails/{id}
curl -X PATCH 'https://api.iresendly.com/emails/{id}' \
  -H 'Authorization: Bearer irs_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "scheduled_at": "2026-11-20T09:00:00Z"
}'
Response
{
  "object": "email",
  "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c"
}

Cancel a scheduled email

POST/emails/{id}/cancel

Cancels an email that hasn't gone out yet and returns it to your quota. Returns 409 if it's already being sent.

Path parameters
  • idstringrequired

    The email id.

POST/emails/{id}/cancel
curl -X POST 'https://api.iresendly.com/emails/{id}/cancel' \
  -H 'Authorization: Bearer irs_xxxxxxxxx'
Response
{
  "object": "email",
  "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c"
}
Still stuck? Write to us and we'll reply by email.Contact ussupport@iresendly.com