MepMail Emails API

Send, schedule, read and cancel emails.

GitHub OpenAPI

Operations 8

POST /emails Send an email #
GET /emails List emails #
POST /emails/batch Send a batch of emails #
POST /emails/{id}/cancel Cancel a scheduled email #
PATCH /emails/{id} Reschedule an email #
GET /emails/{id} Retrieve an email #
DELETE /emails/{id} Delete an email #
GET /emails/{id}/insights Get email insights #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/mepmail-dev:mepmail-dev-emails-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

mepmail-dev-emails-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Mepmail Dev Emails API
  version: 1.0.0
  description: 'Operations tagged Emails across 2 of this provider''s published API definitions: docs.json, mepmail-dev-docs-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mepmail.dev
  description: MepMail Cloud
- url: '{baseUrl}'
  description: Self-hosted instance
  variables:
    baseUrl:
      default: http://localhost:3001
security:
- apiKey: []
tags:
- name: Emails
  description: Send, schedule, read and cancel emails.
paths:
  /emails:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailRequest'
            example:
              from: Acme <hello@yourdomain.com>
              to:
              - customer@example.com
              subject: Your order has shipped
              html: <p>Your order is on its way.</p>
      responses:
        '200':
          description: Email accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendEmailResponse'
              example:
                id: 4ef9a417-02e9-4d39-ad75-9611e0fcc33c
        '401':
          description: Missing, malformed or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Restricted API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Idempotency conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Sending quota exceeded, or the rate limit was exceeded (see Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
      operationId: sendEmail
      summary: Send an email
      tags:
      - Emails
      description: Queues one email for delivery, now or at scheduled_at, from a verified domain of the team.
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Optional retry key, scoped to the team across single and batch sends for 24 hours from the initial claim. The same key and canonical payload replay the original email ids; a different payload returns 409 invalid_idempotent_request and a request still processing returns 409 concurrent_idempotent_requests. An incomplete claim can be recovered after 10 minutes. After expiry, the key can accept a new send. This is an HTTP header, not an email header.
        schema:
          type: string
          minLength: 1
        example: order-123-confirmation
    get:
      parameters:
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          description: Page size, 1-100 (default 20)
        required: false
        description: Page size, 1-100 (default 20)
        name: limit
        in: query
      - schema:
          type: string
          format: uuid
          description: 'Cursor: id of the last item of the previous page. Must be an id this list returned; there is no sentinel value.'
        required: false
        description: 'Cursor: id of the last item of the previous page. Must be an id this list returned; there is no sentinel value.'
        name: after
        in: query
      - schema:
          type: string
          format: uuid
          description: 'Cursor: id of the first item of the next page (page backwards); same rule as after.'
        required: false
        description: 'Cursor: id of the first item of the next page (page backwards); same rule as after.'
        name: before
        in: query
      responses:
        '200':
          description: Emails
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEmailsResponse'
              example:
                object: list
                data:
                - id: 4ef9a417-02e9-4d39-ad75-9611e0fcc33c
                  from: Acme <hello@yourdomain.com>
                  to:
                  - customer@example.com
                  cc:
                  - cc
                  bcc:
                  - bcc
                  reply_to:
                  - support@yourdomain.com
                  subject: Your order has shipped
                  created_at: '2026-10-19T12:00:00.000Z'
                  scheduled_at: '2026-10-19T12:00:00.000Z'
                  last_event: last event
                has_more: false
        '401':
          description: Missing, malformed or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Restricted API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 'Rate limit exceeded: 600 requests per minute per API key and 3,000 per team; wait for Retry-After'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: listEmails
      summary: List emails
      tags:
      - Emails
      description: Lists the team's sent and scheduled emails, newest first, one page at a time.
    servers:
    - url: https://api.mepmail.dev
      description: MepMail Cloud
    - url: '{baseUrl}'
      description: Self-hosted instance
      variables:
        baseUrl:
          default: http://localhost:3001
  /emails/batch:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchEmailRequest'
            example:
            - from: Acme <hello@yourdomain.com>
              to:
              - customer@example.com
              subject: Your order has shipped
              html: <p>Your order is on its way.</p>
            - from: Acme <hello@yourdomain.com>
              to:
              - another@example.com
              subject: Your order has shipped
              html: <p>Your order is on its way.</p>
      responses:
        '200':
          description: Batch accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchEmailResponse'
              example:
                data:
                - id: ae2014de-c168-4c61-8267-70d2662a1ce1
                - id: faccb7a5-8a28-4e9a-ac64-8da1cc3bc1cb
        '401':
          description: Missing, malformed or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Restricted API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Idempotency conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Sending quota exceeded, or the rate limit was exceeded (see Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
      operationId: sendEmailBatch
      summary: Send a batch of emails
      tags:
      - Emails
      description: Queues up to 100 different emails in one request; each item is a send request.
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Optional retry key, scoped to the team across single and batch sends for 24 hours from the initial claim. The same key and canonical payload replay the original email ids; a different payload returns 409 invalid_idempotent_request and a request still processing returns 409 concurrent_idempotent_requests. An incomplete claim can be recovered after 10 minutes. After expiry, the key can accept a new send. This is an HTTP header, not an email header.
        schema:
          type: string
          minLength: 1
        example: order-123-confirmation
    servers:
    - url: https://api.mepmail.dev
      description: MepMail Cloud
    - url: '{baseUrl}'
      description: Self-hosted instance
      variables:
        baseUrl:
          default: http://localhost:3001
  /emails/{id}/cancel:
    post:
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: id
        in: path
      responses:
        '200':
          description: Email canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelEmailResponse'
              example:
                object: email
                id: ae2014de-c168-4c61-8267-70d2662a1ce1
        '401':
          description: Missing, malformed or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Not cancelable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 'Rate limit exceeded: 600 requests per minute per API key and 3,000 per team; wait for Retry-After'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: cancelEmail
      summary: Cancel a scheduled email
      tags:
      - Emails
      description: Cancels an email that is still scheduled, so it is never sent.
    servers:
    - url: https://api.mepmail.dev
      description: MepMail Cloud
    - url: '{baseUrl}'
      description: Self-hosted instance
      variables:
        baseUrl:
          default: http://localhost:3001
  /emails/{id}:
    patch:
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEmailRequest'
            example:
              scheduled_at: '2026-10-20T09:00:00-03:00'
      responses:
        '200':
          description: Email rescheduled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateEmailResponse'
              example:
                object: email
                id: ae2014de-c168-4c61-8267-70d2662a1ce1
        '401':
          description: Missing, malformed or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Not reschedulable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 'Rate limit exceeded: 600 requests per minute per API key and 3,000 per team; wait for Retry-After'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: updateEmail
      summary: Reschedule an email
      tags:
      - Emails
      description: Moves a scheduled email to a new scheduled_at before it is sent.
    get:
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: id
        in: path
      responses:
        '200':
          description: Email
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetEmailResponse'
              example:
                id: ae2014de-c168-4c61-8267-70d2662a1ce1
                from: Acme <hello@yourdomain.com>
                to:
                - customer@example.com
                cc:
                - cc
                bcc:
                - bcc
                reply_to:
                - support@yourdomain.com
                subject: Your order has shipped
                created_at: '2026-10-19T12:00:00.000Z'
                scheduled_at: '2026-10-19T12:00:00.000Z'
                last_event: last event
                object: email
                html: <p>Your order is on its way.</p>
                text: Your order is on its way.
                message_id: ae2014de-c168-4c61-8267-70d2662a1ce1
                score: 1
        '401':
          description: Missing, malformed or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Restricted API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 'Rate limit exceeded: 600 requests per minute per API key and 3,000 per team; wait for Retry-After'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getEmail
      summary: Retrieve an email
      tags:
      - Emails
      description: Returns one email with its recipients, content and last delivery event.
    delete:
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: id
        in: path
      responses:
        '200':
          description: Email deleted, including its events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveEmailResponse'
              example:
                object: email
                id: ae2014de-c168-4c61-8267-70d2662a1ce1
                deleted: true
        '401':
          description: Missing, malformed or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Restricted API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 'Rate limit exceeded: 600 requests per minute per API key and 3,000 per team; wait for Retry-After'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: deleteEmail
      summary: Delete an email
      tags:
      - Emails
      description: Deletes an email and its events from the log.
    servers:
    - url: https://api.mepmail.dev
      description: MepMail Cloud
    - url: '{baseUrl}'
      description: Self-hosted instance
      variables:
        baseUrl:
          default: http://localhost:3001
  /emails/{id}/insights:
    get:
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: id
        in: path
      responses:
        '200':
          description: Best-practice check results and score computed when the email was sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailInsightsResponse'
              example:
                object: email_insights
                email_id: ae2014de-c168-4c61-8267-70d2662a1ce1
                score: 1
                score_version: 1
                band: excellent
                marketing: false
                html_size_bytes: 1
                computed_at: '2026-10-19T12:00:00.000Z'
                checks:
                - id: 4ef9a417-02e9-4d39-ad75-9611e0fcc33c
                  severity: critical
                  status: pass
                  penalty: 1
                  detail: {}
        '401':
          description: Missing, malformed or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Restricted API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 'Rate limit exceeded: 600 requests per minute per API key and 3,000 per team; wait for Retry-After'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getEmailInsights
      summary: Get email insights
      tags:
      - Emails
      description: Returns the best-practice checks and the score computed when the email was sent.
    servers:
    - url: https://api.mepmail.dev
      description: MepMail Cloud
    - url: '{baseUrl}'
      description: Self-hosted instance
      variables:
        baseUrl:
          default: http://localhost:3001
components:
  schemas:
    BatchEmailRequest:
      type: array
      items: {}
      minItems: 1
      maxItems: 100
    RemoveEmailResponse:
      type: object
      properties:
        object:
          type: string
          enum:
          - email
        id:
          type: string
          format: uuid
        deleted:
          type: boolean
          enum:
          - true
      required:
      - object
      - id
      - deleted
    SendEmailRequest:
      type: object
      properties:
        from:
          type: string
          description: Sender, "Name <user@domain>" or bare address; the domain must be verified for the team
          example: Acme <hello@yourdomain.com>
        to:
          anyOf:
          - type: string
          - type: array
            items:
              type: string
            minItems: 1
            maxItems: 50
          description: Recipient address or list of up to 50
          example:
          - customer@example.com
        subject:
          type: string
          minLength: 1
          description: Subject line
        html:
          type: string
          description: HTML body; at least one of html/text is required
        text:
          type: string
          description: Plain-text body; at least one of html/text is required
        cc:
          anyOf:
          - type: string
          - type: array
            items:
              type: string
            minItems: 1
            maxItems: 50
          description: Cc address or list
        bcc:
          anyOf:
          - type: string
          - type: array
            items:
              type: string
            minItems: 1
            maxItems: 50
          description: Bcc address or list
        reply_to:
          anyOf:
          - type: string
          - type: array
            items:
              type: string
            minItems: 1
            maxItems: 50
          description: Reply-To address or list
        scheduled_at:
          type: string
          description: 'Deliver later: ISO 8601 with offset, or relative like "in 2 hours" (an ISO 8601 datetime with offset (e.g. "2026-09-01T12:00:00Z") or a relative time like "in 5 mins", "in 2 hours", or "in 1 day"); max 30 days ahead'
        tags:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                minLength: 1
              value:
                type: string
            required:
            - name
            - value
          description: Key/value labels attached to the email for filtering
        topic_id:
          type:
          - string
          - 'null'
          format: uuid
          description: 'Topic id: recipients opted out of the topic are skipped and an unsubscribe link is added'
        attachments:
          type: array
          items:
            type: object
            properties:
              filename:
                type: string
                minLength: 1
              content:
                type: string
              content_type:
                type: string
              content_id:
                type: string
              path:
                type: string
            required:
            - filename
          description: Attachments with base64 content (no remote paths)
        headers:
          type: object
          additionalProperties:
            type: string
          description: Extra message headers (transport headers are rejected)
        template:
          description: 'Not supported yet: any value is a 422. Send html/text instead'
      required:
      - from
      - to
      - subject
    UpdateEmailResponse:
      type: object
      properties:
        object:
          type: string
          enum:
          - email
        id:
          type: string
          format: uuid
      required:
      - object
      - id
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
        name:
          type: string
        message:
          type: string
      required:
      - statusCode
      - name
      - message
    UpdateEmailRequest:
      type: object
      properties:
        scheduled_at:
          type: string
      required:
      - scheduled_at
    CancelEmailResponse:
      type: object
      properties:
        object:
          type: string
          enum:
          - email
        id:
          type: string
          format: uuid
      required:
      - object
      - id
    ListEmailsResponse:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              from:
                type: string
              to:
                type: array
                items:
                  type: string
              cc:
                type:
                - array
                - 'null'
                items:
                  type: string
              bcc:
                type:
                - array
                - 'null'
                items:
                  type: string
              reply_to:
                type:
                - array
                - 'null'
                items:
                  type: string
              subject:
                type: string
              created_at:
                type: string
              scheduled_at:
                type:
                - string
                - 'null'
              last_event:
                type: string
            required:
            - id
            - from
            - to
            - cc
            - bcc
            - reply_to
            - subject
            - created_at
            - scheduled_at
            - last_event
        has_more:
          type: boolean
      required:
      - object
      - data
      - has_more
    EmailInsightsResponse:
      type: object
      properties:
        object:
          type: string
          enum:
          - email_insights
        email_id:
          type: string
          format: uuid
        score:
          type: number
          description: Best-practice score, 0-10, one decimal
        score_version:
          type: integer
        band:
          type: string
          enum:
          - excellent
          - good
          - needs_attention
          - at_risk
        marketing:
          type: boolean
        html_size_bytes:
          type:
          - integer
          - 'null'
        computed_at:
          type: string
        checks:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Check id from the @millionsend/core check catalog
              severity:
                type: string
                enum:
                - critical
                - major
                - minor
                - info
              status:
                type: string
                enum:
                - pass
                - fail
                - passed_by_design
                - not_applicable
                - unknown
              penalty:
                type: number
                description: Points deducted from the score; 0 unless status is fail
              detail:
                type: object
                additionalProperties: {}
            required:
            - id
            - severity
            - status
            - penalty
      required:
      - object
      - email_id
      - score
      - score_version
      - band
      - marketing
      - html_size_bytes
      - computed_at
      - checks
    BatchEmailResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
            required:
            - id
        errors:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                type: string
            required:
            - index
            - message
      required:
      - data
    GetEmailResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        from:
          type: string
        to:
          type: array
          items:
            type: string
        cc:
          type:
          - array
          - 'null'
          items:
            type: string
        bcc:
          type:
          - array
          - 'null'
          items:
            type: string
        reply_to:
          type:
          - array
          - 'null'
          items:
            type: string
        subject:
          type: string
        created_at:
          type: string
        scheduled_at:
          type:
          - string
          - 'null'
        last_event:
          type: string
        object:
          type: string
          enum:
          - email
        html:
          type:
          - string
          - 'null'
        text:
          type:
          - string
          - 'null'
        message_id:
          type: string
        score:
          type:
          - number
          - 'null'
      required:
      - id
      - from
      - to
      - cc
      - bcc
      - reply_to
      - subject
      - created_at
      - scheduled_at
      - last_event
      - object
      - html
      - text
      - message_id
      - score
    SendEmailResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
      required:
      - id
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'An API key from the dashboard (ms_…), sent as Authorization: Bearer. A sending-only key reaches the /emails routes only.'
x-refined-from:
- docs.json
- mepmail-dev-docs-openapi.json
x-provenance:
  method: harvested
  publisher: MepMail
  source: https://docs.mepmail.dev/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)