Authorization

API Key: The x-api-key header must be included with every request to authenticate the client. Requests without this header will return a 401 Unauthorized error.

Example:

x-api-key: YOUR_API_KEY

1. Send Email

POST /email

Sends an email message. The message can be directly specified or templated.

Headers

• x-api-key (required): API key for authorization.

Request Body

Sample Request (Non Templated)

{
  "to": "recipient@example.com",
  "from": "sender@example.com",
  "subject": "Test Email",
  "message": "Hello, this is a test email message."
}

Sample Request (Templated)

{
    "to": "recipient@example.com",
    "from": "sender@example.com",
    "templateId": "gPVTbWpwQHXgg8KSZ6sX",
    "clientId": "23948729438slkdfjwkfjhsdfsdf",
    "variables": {
      "name": "Jane Doe",
      "time": "10:49pm"
    }
}

Sample Response

200 OK

{
  "message": "Email received successfully",
  "trackingId": "1234567890abcdef"
}

Response Fields

Rate Limiting

To ensure fair usage of resources, the Send Email API endpoint is rate-limited based on each client’s API key. If the rate limit is exceeded, subsequent requests will be temporarily blocked until the rate limit resets.

Current Rate Limit

The current rate limit may vary based on your subscription plan and usage agreement. Please refer to the API’s response headers to monitor your rate limit status, or contact us for your specific rate limit settings.

Rate Limit Headers

On each response, the following headers provide rate limit details:

Exceeded Rate Limit Response

If the rate limit is exceeded, the following response will be returned:

{
  "error": "Rate limit exceeded"
}

Increasing Rate Limit

If your application requires a higher rate limit, please reach out to the eMsgNow support team to discuss rate limit adjustments that suit your requirements. We are happy to accommodate higher traffic where possible. Contact us via email at support@emsgnow.com or through your eMsgNow representative.

2. Get Email Details

GET /email/:messageId

Retrieves the full details of an email message, including events related to the email.

Headers

• x-api-key (required): API key for authorization.

Sample Request

GET /email/1234567890abcdef

Sample Response

{
  "to": "recipient@example.com",
  "from": "sender@example.com",
  "subject": "Test Email",
  "message": "Hello, this is a test email message.",
  "clientId": "23948729438slkdfjwkfjhsdfsdf",
  "messageType": "email",
  "trackingId": "1234567890abcdef",
  "notBefore": "2024-11-10T02:48:08.004Z",
  "notAfter": "2024-11-10T08:48:08.004Z",
  "created": "2024-11-10T18:18:31.050Z",
  "updated": "2024-11-10T18:18:31.050Z",
  "events": [
    {
      "id": "5mogLKKETFjg7c3eNNvH",
      "message": {
        "channel": "email",
        "trackingId": "1234567890abcdef",
        "clientId": "23948729438slkdfjwkfjhsdfsdf",
        "status": "processing",
        "statusAt": "2024-11-10T02:48:08.019Z",
        "additionalInfo": {}
      },
      "timestamp": "2024-11-10T18:18:31.050Z"
    },
    {
      "id": "C98OWsv63rVLJoE5QAns",
      "message": {
        "channel": "email",
        "trackingId": "1234567890abcdef",
        "clientId": "23948729438slkdfjwkfjhsdfsdf",
        "status": "sent",
        "statusAt": "2024-11-10T02:48:08.019Z",
        "additionalInfo": {}
      },
      "timestamp": "2024-11-10T18:18:31.050Z"
    }
  ]
}

Response Fields

3. Get Email Events

GET /email/:messageId/events

Retrieves a list of events associated with a specific email message.

Headers

• x-api-key (required): API key for authorization.

Sample Request

GET /email/1234567890abcdef/events

Sample Response

{
  "messageId": "1234567890abcdef",
  "events": [
    {
      "id": "5mogLKKETFjg7c3eNNvH",
      "message": {
        "channel": "email",
        "trackingId": "1234567890abcdef",
        "clientId": "23948729438slkdfjwkfjhsdfsdf",
        "status": "processing",
        "statusAt": "2024-11-10T02:48:08.019Z",
        "additionalInfo": {}
      },
      "timestamp": "2024-11-10T18:18:31.050Z"
    },
    {
      "id": "C98OWsv63rVLJoE5QAns",
      "message": {
        "channel": "email",
        "trackingId": "1234567890abcdef",
        "clientId": "23948729438slkdfjwkfjhsdfsdf",
        "status": "sent",
        "statusAt": "2024-11-10T02:48:08.019Z",
        "additionalInfo": {}
      },
      "timestamp": "2024-11-10T18:18:31.050Z"
    }
  ]
}

Response Fields

Events Array

Each event object within the events array provides details about the status of the email message at different stages.

4. Get Single Email Event

GET /email/:messageId/events/:eventId

Retrieves a specific event associated with an email message.

Headers

• x-api-key (required): API key for authorization.

Sample Request

GET /email/1234567890abcdef/events/5mogLKKETFjg7c3eNNvH

Sample Response

{
  "messageId": "1234567890abcdef",
  "id": "5mogLKKETFjg7c3eNNvH",
  "message": {
    "channel": "email",
    "trackingId": "1234567890abcdef",
    "clientId": "1",
    "status": "processing",
    "statusAt": "2024-11-10T02:48:08.019Z",
    "additionalInfo": {}
  },
  "timestamp": "2024-11-10T18:18:31.050Z"
}

Get Single Email Event Response Data

Message Object

The message object within the event provides additional details about the email status at the time of the event.

Error Responses

401 Unauthorized

{
  "error": "API key is required"
}

403 Forbidden

{
  "error": "Invalid API key"
}

500 Internal Server Error

{
  "error": "Failed to retrieve email status"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded"
}