Email Status API

Email Status API

The Email Status API is part of the Domains API and lets you retrieve the current delivery status of an email sent through POST /api/v1/send, including the reason when it bounced or was flagged as spam.

Use the id returned by the Send endpoint together with the ID of the domain the email was sent from.

Only HTTPS is supported

Authentication

Email Status requests can be authenticated with either:

• an Organization API token via MailPace-Organization-Token, which can access any domain in the organization, or
• the domain's Server token via MailPace-Server-Token, which can only access that domain.

The :domain_id in the URL must match the domain that owns the email. Requests for emails belonging to another domain return 404 Not Found.

Required headers:

Header Name	Contents
Accept	application/json	Required
Content-Type	application/json	Required
MailPace-Organization-Token	Organization API token	Required, unless using MailPace-Server-Token
MailPace-Server-Token	Domain API token	Required, unless using MailPace-Organization-Token

You can create and revoke Organization API tokens from your Organization's API Tokens page, and find a domain's Server token on that domain's API Tokens page in the MailPace dashboard.

Get an email's status

GET /api/v1/domains/:domain_id/emails/:id

Name	Type	Notes
domain_id	integer	ID of the domain the email was sent from	Required
id	integer	Email ID returned by POST /api/v1/send	Required

Using an Organization API token:

curl "https://app.mailpace.com/api/v1/domains/123/emails/456" \
  -X GET \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "MailPace-Organization-Token: ORGANIZATION_TOKEN_GOES_HERE"

Using the domain's Server token:

curl "https://app.mailpace.com/api/v1/domains/123/emails/456" \
  -X GET \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "MailPace-Server-Token: TOKEN_GOES_HERE"

Example response

{
  "id": 456,
  "domain_id": 123,
  "status": "bounced",
  "message_id": "<4c0f6d2a-6f2b-4b1e-9d1a-1b2c3d4e5f60@mailer.ohmysmtp.com>",
  "from": "Example <hello@example.com>",
  "to": "recipient@example.org",
  "cc": null,
  "bcc": null,
  "subject": "Welcome",
  "replyto": null,
  "inreplyto": null,
  "references": null,
  "list_unsubscribe": null,
  "tags": ["welcome"],
  "bounce_reason": "550 5.7.1 Message rejected as spam",
  "bounce": {
    "category": "spam",
    "response": "550 5.7.1 Message rejected as spam",
    "fbl": "abuse",
    "to": "recipient@example.org",
    "return_path": "bounces@example.com",
    "sequence": "1",
    "message_id": "<4c0f6d2a-6f2b-4b1e-9d1a-1b2c3d4e5f60@mailer.ohmysmtp.com>",
    "created_at": "2026-10-22T12:00:00.000Z"
  },
  "deferred": null,
  "created_at": "2026-10-22T11:59:59.000Z",
  "modified_at": "2026-10-22T12:00:00.000Z"
}

Email fields

Field	Type	Description
id	integer	Email ID
domain_id	integer	ID of the domain the email was sent from
status	string	Current status: queued, delivered, deferred, bounced, or spam. See Email Lifecycle for details
message_id	string	Message-ID header used for the email
from	string	From address
to	string	To address(es)
cc	string	CC address(es), or null
bcc	string	BCC address(es), or null
subject	string	Subject, or null
replyto	string	Reply-To address, or null
inreplyto	string	In-Reply-To header, or null
references	string	References header, or null
list_unsubscribe	string	List-Unsubscribe header, or null
tags	array of strings	Tags attached to the email
bounce_reason	string	Reason for the current bounce, spam classification, or deferral, when there is one. Otherwise null
bounce	object	Most recent hard bounce or spam report, or null. See below
deferred	object	Most recent soft bounce (deferral), or null. See below
created_at	string	Time the email was accepted
modified_at	string	Time the email was last updated

Bounce object

bounce is null unless a hard bounce or spam report exists.

Field	Type	Description
category	string	Bounce category, for example spam
response	string	Response returned by the receiving server
fbl	string	Feedback loop information, when supplied
to	string	Recipient the report relates to
return_path	string	Return-Path used for the email
sequence	string	Bounce sequence number
message_id	string	Message-ID the report relates to
created_at	string	Time the bounce report was received

Deferred object

deferred is null unless the email has been deferred by a receiving server.

Field	Type	Description
category	string	Deferral category
response	string	Response returned by the receiving server
defcount	integer	Number of delivery attempts so far
next_attempt	string	Time of the next delivery attempt, or null
to	string	Recipient being delivered to
mx	string	MX host that responded
host	string	Host that responded
ip	string	IP address that responded
created_at	string	Time the deferral was recorded

Errors and status codes

• 200 OK: Request succeeded
• 401 Unauthorized: Missing, invalid, or revoked token
• 404 Not Found: The domain or email was not found, or the email does not belong to the specified domain