Messages

Every time you send an email via Mailjet, a new message object is created. The resources below help you retrieve details about these messages - sending time, delivery and contact engagement info, recipients, message size, etc.

get

Get detailed information on all processed messages

get

Get detailed information on a specific processed message

get

Get the event history for a specific message

get

Retrieve sending / size / spam information about all messages

get

Retrieve sending / size / spam information about a specific message ID

get

Get a list of event summaries for all messages

get

Get an event summary for a specific message

get

/message

Get a list of messages with specific information on the type of content, tracking, sending and delivery.

Full API path

https://api.mailjet.com/v3/REST/message

Query string parameters

Campaign

integer

Retrieves only messages sent as part of the specified Campaign ID.

Contact

integer

Retrieves only messages sent to the specified Contact ID.

CustomID

string

Retrieves only messages tagged with the specified CustomID.

Destination

integer

Retrieves only messages sent to the specified Destination ID (ID for a specific domain name).

FromTS

string

Retrieves only messages sent after the specified timestamp.

FromType

integer

Retrieves only messages of the specified type:

  • 1 - Transactional
  • 2 - Marketing
  • 3 - Unknown

MessageState

integer

Retrieves only non-delivered messages with the respective State ID. The MessageState ID explains why a message was not delivered successfully to the recipient:

  • 1 = user unknown (recipient)
  • 2 = mailbox inactive (recipient)
  • 3 = quota exceeded (recipient)
  • 4 = invalid domain (domain)
  • 5 = no mail host (domain)
  • 6 = relay/access denied (domain)
  • 7 = sender blocked (spam)
  • 8 = content blocked (spam)
  • 9 = policy issue (spam)
  • 10 = system issue (system)
  • 11 = protocol issue (system)
  • 12 = connection issue (system)
  • 13 = greylisted (domain)
  • 14 = preblocked (Mailjet)
  • 15 = duplicate in campaign (Mailjet)
  • 16 = spam preblocked (Mailjet)
  • 17 = bad or empty template (content)
  • 18 = error in template language (content)
  • 19 = typofix (domain)
  • 20 = blacklisted (recipient)
  • 21 = spam reporter (recipient)

MessageStatus

integer

Retrieves only messages with the specified status:

  • 0 (Processed)
  • 1 (Queued)
  • 2 (Sent)
  • 3 (Opened)
  • 4 (Clicked)
  • 5 (Bounce)
  • 6 (Spam)
  • 7 (Unsub)
  • 8 (Blocked)
  • 9 (SoftBounce)
  • 10 (HardBounce)
  • 11 (Deferred)

PlanSubscription

integer

Retrieves only messages with the specified PlanSubscription ID.

SenderID

integer

Retrieves only messages sent using a sender address with the specified ID.

ShowContactAlt

boolean

When true, the recipient's email address will be displayed in the message object under ContactAlt.

Default value: false

ShowSubject

boolean

When true, the subject of the message will be displayed under Subject.

Default value: false

ToTs

string

Retrieves only messages sent before the specified timestamp.

Limit

integer

Limit the response to a select number of returned objects.

Default value: 10. Maximum value: 1000

Offset

integer

Retrieve a list of objects starting from a certain offset. Combine this query parameter with Limit to retrieve a specific section of the list of objects.

Default value: 0

countOnly

boolean

Set the value of this query parameter to 1 to retrieve the overall number of objects returned by this request for your API Key. No list of results will be returned - the objects will simply be counted.

Default value: 0

Note: When you send a request without the countOnly query parameter, Count and Total will only return the number of extracted elements and not the overall number.

Sort

string

Specify a property name for this query parameter to sort the objects in Data. By default the sorting is ascending. When a property name is postfixed with DESC (i.e. property_name DESC), the sort order will be descending.

Note: Both the Sort query parameter and the option to select a descending order are not available for every property.

Responses

Note: You can find all the errors related to API in the error page

Count

integer

Data

array

ArrivedAt

string

Timestamp indicating when the message arrived in the recipient's mailbox.

AttachmentCount

integer

Number of attachments detected for this message.

AttemptCount

integer

Number of attempts made to deliver this message.

CampaignID

integer

Unique numeric ID for the campaign this message is part of.

ContactAlt

string

The email address of the contact, to which the message was sent. Displayed only when ShowContactAlt=true.

ContactID

integer

Unique numeric ID for the contact, to which the message was sent.

Delay

number

Delay between the message being processed and it being delivered (in milliseconds).

DestinationID

integer

Unique numeric ID of the recipient email's domain.

FilterTime

integer

Time spent processing the text of the message (in milliseconds).

ID

integer

Unique numeric ID of this message.

IsClickTracked

boolean

Indicates whether clicks are tracked for this message or not.

IsHTMLPartIncluded

boolean

Indicates whether the message includes any HTML content (Html-part!=null) or not.

IsOpenTracked

boolean

Indicates whether opens are tracked for this message or not.

IsTextPartIncluded

boolean

Indicates whether the message includes a plain text part (Text-part!=null) or not.

IsUnsubTracked

boolean

Indicates whether unsubscriptions are tracked for this message or not.

MessageSize

integer

Indicates the message size (in bytes).

SenderID

integer

Unique numeric ID of the sender email address.

SpamassassinScore

number

SpamAssassin score for this message.

SpamassRules

string

Matched SpamAssassin rules.

StatePermanent

boolean

Indicates whether the current state of the message is permanent (i.e. cannot be changed anymore) or not.

Status

string

Current message status.

Possible values:

  • unknown
  • queued
  • sent
  • opened
  • clicked
  • bounce
  • spam
  • unsub
  • blocked
  • hardbounce
  • softbounce
  • deferred

Subject

string

The subject line for this message. Displayed only when ShowSubject=true.

UUID

string

Unique 128-bit ID for this message.

Note: Returns values only for accounts created after April 5th, 2018.

Total

integer

get

/message/{message_ID}

Retrieve specific information on the type of content, tracking, sending and delivery for a specific processed message.

Full API path

https://api.mailjet.com/v3/REST/message/{message_ID}

Path parameters

message_ID

integer, required

Unique numeric ID of the message you want to retrieve.

Responses

Note: You can find all the errors related to API in the error page

Count

integer

Data

array

ArrivedAt

string

Timestamp indicating when the message arrived in the recipient's mailbox.

AttachmentCount

integer

Number of attachments detected for this message.

AttemptCount

integer

Number of attempts made to deliver this message.

CampaignID

integer

Unique numeric ID for the campaign this message is part of.

ContactAlt

string

The email address of the contact, to which the message was sent. Displayed only when ShowContactAlt=true.

ContactID

integer

Unique numeric ID for the contact, to which the message was sent.

Delay

number

Delay between the message being processed and it being delivered (in milliseconds).

DestinationID

integer

Unique numeric ID of the recipient email's domain.

FilterTime

integer

Time spent processing the text of the message (in milliseconds).

ID

integer

Unique numeric ID of this message.

IsClickTracked

boolean

Indicates whether clicks are tracked for this message or not.

IsHTMLPartIncluded

boolean

Indicates whether the message includes any HTML content (Html-part!=null) or not.

IsOpenTracked

boolean

Indicates whether opens are tracked for this message or not.

IsTextPartIncluded

boolean

Indicates whether the message includes a plain text part (Text-part!=null) or not.

IsUnsubTracked

boolean

Indicates whether unsubscriptions are tracked for this message or not.

MessageSize

integer

Indicates the message size (in bytes).

SenderID

integer

Unique numeric ID of the sender email address.

SpamassassinScore

number

SpamAssassin score for this message.

SpamassRules

string

Matched SpamAssassin rules.

StatePermanent

boolean

Indicates whether the current state of the message is permanent (i.e. cannot be changed anymore) or not.

Status

string

Current message status.

Possible values:

  • unknown
  • queued
  • sent
  • opened
  • clicked
  • bounce
  • spam
  • unsub
  • blocked
  • hardbounce
  • softbounce
  • deferred

Subject

string

The subject line for this message. Displayed only when ShowSubject=true.

UUID

string

Unique 128-bit ID for this message.

Note: Returns values only for accounts created after April 5th, 2018.

Total

integer

get

/messagehistory/{message_ID}

Retrieve the event history (sending, open, click etc.) for a specific message.

Full API path

https://api.mailjet.com/v3/REST/messagehistory/{message_ID}

Path parameters

message_ID

integer, required

Unique numeric ID of the message, whose event history you want to retrieve.

Responses

Note: You can find all the errors related to API in the error page

Count

integer

Data

array

Comment

string

A comment providing additional details in case of issues with the message delivery.

EventAt

integer

Timestamp indicating when the event was registered.

EventType

string

The type of this event.

Possible values:

  • sent
  • opened
  • clicked
  • bounced
  • blocked
  • unsub
  • spam

State

string

When the message is not successfully delivered, will display the reason for non-delivery.

Useragent

string

User agent (browser) used to trigger the event (when applicable).

UseragentID

integer

Unique numeric ID of the user agent (browser) used to trigger this event.

Total

integer

get

/messageinformation

Retrieve sending / size / spam information about all messages.

Full API path

https://api.mailjet.com/v3/REST/messageinformation

Query string parameters

CampaignID

integer

Retrieves information only about messages that are part of this campaign.

ContactsList

integer

Retrieves information only about messages that were sent to this contact list.

CustomCampaign

string

Retrieves information only about messages that are part of a campaign with the specified Custom ID.

From

string

Retrieves information only about messages sent from the specified sender email address.

FromDomain

string

Retrieves information only about messages sent from the specified sender domain.

FromID

integer

Retrieves information only about messages sent from the specified sender ID.

FromTS

string

Retrieves information only about messages sent after the specified timestamp.

FromType

integer

Retrieves information only for a specific type of messages:

  • 1 - Transactional
  • 2 - Marketing
  • 3 - Unknown

IsDeleted

boolean

When true, will retrieve information only for messages that are part of deleted campaigns. When false, messages from deleted campaigns will be excluded from the response.

IsNewsletterTool

boolean

When true, will retrieve information only for campaigns created with the Legacy template builder. When false, campaigns created with the Legacy builder will be excluded from the response.

IsStarred

boolean

When true, will retrieve information only for messages that are part of starred campaigns. When false, messages from starred campaigns will be excluded from the response.

MessageStatus

integer

Retrieves information only for messages with the specified status:

  • 0 (Processed)
  • 1 (Queued)
  • 2 (Sent)
  • 3 (Opened)
  • 4 (Clicked)
  • 5 (Bounce)
  • 6 (Spam)
  • 7 (Unsub)
  • 8 (Blocked)
  • 9 (SoftBounce)
  • 10 (HardBounce)
  • 11 (Deferred)

Period

string

Retrieves information only for messages sent between the start of the selected period and the current timestamp.

  • Day - since the start of the current day
  • Week - since the start of the current week
  • Month - since the start of the current month
  • Year - since the start of the current year

ToTS

string

Retrieves information only for messages sent before the specified timestamp.

Limit

integer

Limit the response to a select number of returned objects.

Default value: 10. Maximum value: 1000

Offset

integer

Retrieve a list of objects starting from a certain offset. Combine this query parameter with Limit to retrieve a specific section of the list of objects.

Default value: 0

countOnly

boolean

Set the value of this query parameter to 1 to retrieve the overall number of objects returned by this request for your API Key. No list of results will be returned - the objects will simply be counted.

Default value: 0

Note: When you send a request without the countOnly query parameter, Count and Total will only return the number of extracted elements and not the overall number.

Sort

string

Specify a property name for this query parameter to sort the objects in Data. By default the sorting is ascending. When a property name is postfixed with DESC (i.e. property_name DESC), the sort order will be descending.

Note: Both the Sort query parameter and the option to select a descending order are not available for every property.

Responses

Note: You can find all the errors related to API in the error page

Count

integer

Data

array

CampaignID

integer

Unique numeric ID of the campaign this message is part of.

ClickTrackedCount

integer

Number of messages, for which click tracking is enabled.

ContactID

integer

Unique numeric ID of the contact, to which the message was sent.

CreatedAt

string

Timestamp indicating when the message was created.

ID

integer

Unique numeric ID of this message.

MessageSize

integer

Size of the message (in bytes).

OpenTrackedCount

integer

Number of messages, for which open tracking is enabled.

QueuedCount

integer

Number of messages waiting in the send queue.

SendEndAt

string

Timestamp indicating when last message was sent for the campaign.

SentCount

integer

Number of actual sent attempts.

SpamAssassinRules

object

Matched SpamAssassin rules.

SpamAssassinScore

number

SpamAssassin score for this message.

Total

integer

get

/messageinformation/{message_ID}

Retrieve sending / size / spam information about a specific message ID.

Full API path

https://api.mailjet.com/v3/REST/messageinformation/{message_ID}

Path parameters

message_ID

integer, required

Unique numeric ID of the message you want to retrieve information about.

Responses

Note: You can find all the errors related to API in the error page

Count

integer

Data

array

CampaignID

integer

Unique numeric ID of the campaign this message is part of.

ClickTrackedCount

integer

Number of messages, for which click tracking is enabled.

ContactID

integer

Unique numeric ID of the contact, to which the message was sent.

CreatedAt

string

Timestamp indicating when the message was created.

ID

integer

Unique numeric ID of this message.

MessageSize

integer

Size of the message (in bytes).

OpenTrackedCount

integer

Number of messages, for which open tracking is enabled.

QueuedCount

integer

Number of messages waiting in the send queue.

SendEndAt

string

Timestamp indicating when last message was sent for the campaign.

SentCount

integer

Number of actual sent attempts.

SpamAssassinRules

object

Matched SpamAssassin rules.

SpamAssassinScore

number

SpamAssassin score for this message.

Total

integer

get

/messagesentstatistics

Retrieve a list of event summaries for all messages. Each object will provide information on each event type and whether it occurred for this message, as well as general sending information. If no query parameters are used, will return events with `FromTS` equal to the current day at 00:00 UTC.

Note: This is a legacy endpoint, which is not available for users created after March 15th 2018. In order to receive event summaries for messages, please use the /message endpoint instead.

Full API path

https://api.mailjet.com/v3/REST/messagesentstatistics

Query string parameters

AllMessages

boolean

When true, will retrieve summaries for all messages in each campaign. Otherwise only the first message from each campaign will be retrieved.

Default value: false

BounceEventFromTs

string

Retrieves information only about bounced messages, where the bounce occurred after the specified timestamp (BouncedAt >= BounceEventFromTs). Can be used only if CampaignID query parameter is specified as well.

BounceEventToTs

string

Retrieves information only about bounced messages, where the bounce occurred before the specified timestamp (BouncedAt <= BounceEventFromTs). Can be used only if CampaignID query parameter is specified as well.

CampaignID

integer

Retrieves information only about messages linked to the specified campaign ID. Will retrieve only the first message sent for this campaign, unless AllMessages is set to True.

Contact

integer

Retrieves information only about messages sent to this contact ID. Will retrieve only the first message sent to the selected contact, unless AllMessages is set to True.

ContactsList

integer

Retrieves information only about messages sent to contacts from this contact list ID.

CustomCampaign

string

Retrieves information only about messages from the campaign with the specified custom value.

CustomID

string

Retrieves information only about messages tagged with this Custom ID.

From

string

Retrieves information only about messages, which used the specified sender email address.

FromDomain

string

Retrieves information only about messages, which used the specified sender email domain.

FromID

integer

Retrieves information only about messages, which used the specified sender ID.

FromTS

string

Retrieves information only about messages linked to campaigns sent after the specified timestamp. If no query parameters are used, FromTS defaults to the current day at 00:00 UTC.

FromType

integer

Retrieves information only about messages of the specified type:

  • 1 - transactional
  • 2 - marketing
  • 3 - unknown

IsDeleted

boolean

When true, only information about messages from deleted campaigns will be returned. When false, messages from deleted campaigns will be excluded from the response.

IsNewsletterTool

boolean

When true, will return information only about messages from campaigns created by the Newsletter tool (legacy template builder). When false, messages from newsletter campaigns will be excluded.

IsStarred

boolean

When true, will retrieve information only about messages from starred campaigns. When false, messages from starred campaigns will be excluded from the response.

MessageStatus

integer

Retrieves information only about messages with the specified status.

  • 0 (Processed)
  • 1 (Queued)
  • 2 (Sent)
  • 3 (Opened)
  • 4 (Clicked)
  • 5 (Bounce)
  • 6 (Spam)
  • 7 (Unsub)
  • 8 (Blocked)
  • 9 (SoftBounce)
  • 10 (HardBounce)
  • 11 (Deferred)

Period

string

Retrieves information only about sent between the start of the selected period and the current timestamp.

  • Day - since the start of the current day
  • Week - since the start of the current week
  • Month - since the start of the current month
  • Year - since the start of the current year

ProcessEmailAutomationRelations

boolean

When true, will retrieve information only about messages that are sent by an Email Automation scenario.

Default value: false

RawData

boolean

Works toghether with AllMessages. If both are True the method returns only the most important data to reduce database load

ShowExtraData

boolean

Works together with AllMessages. When both are True, the method returns only the most important data to reduce the database load.

SpamEventFromTs

string

Retrieves information only about messages marked as spam, where the spam complaint occurred after the specified timestamp (ComplaintAt >= SpamEventFromTs). Can be used only if CampaignID query parameter is specified as well.

SpamEventToTs

string

Retrieves information only about messages marked as spam, where the spam complaint occurred before the specified timestamp (ComplaintAt <= SpamEventFromTs). Can be used only if CampaignID query parameter is specified as well.

ToTS

string

Retrieves information only about messages sent before the specified timestamp.

WorkflowID

integer

Retrieves information only about messages triggered by the specified automation workflow ID.

Limit

integer

Limit the response to a select number of returned objects.

Default value: 10. Maximum value: 1000

Offset

integer

Retrieve a list of objects starting from a certain offset. Combine this query parameter with Limit to retrieve a specific section of the list of objects.

Default value: 0

countOnly

boolean

Set the value of this query parameter to 1 to retrieve the overall number of objects returned by this request for your API Key. No list of results will be returned - the objects will simply be counted.

Default value: 0

Note: When you send a request without the countOnly query parameter, Count and Total will only return the number of extracted elements and not the overall number.

Sort

string

Specify a property name for this query parameter to sort the objects in Data. By default the sorting is ascending. When a property name is postfixed with DESC (i.e. property_name DESC), the sort order will be descending.

Note: Both the Sort query parameter and the option to select a descending order are not available for every property.

Responses

Note: You can find all the errors related to API in the error page

Count

integer

Data

array

ArrivalTs

string

Timestamp indicating when the message arrived in the recipient's mailbox.

Blocked

boolean

Indicates whether the message was blocked or not.

Bounce

boolean

Indicates whether the message has bounced or not.

BounceDate

string

Timestamp for the bounce event. Only available when ShowExtraData=true.

BounceReason

string

A short description indicating what the reason behind the bounce is. Only available when ShowExtraData=true.

CampaignID

integer

Unique numeric ID for the campaign this message is part of.

Click

boolean

Indicates whether a link in the email (except the unsubscription link) was clicked or not.

CntRecipients

integer

Shows the number of recipients for this campaign, when only the first message from each campaign is retrieved (AllMessages=false).

ComplaintDate

string

Timestamp for the time when the spam complaint was received for this message. Retrieved only when ShowExtraData=true.

ContactID

integer

Unique numeric ID for the contact, to which the message was sent.

Details

string

Indicates the reason for the non-delivery of a message.

FBLSource

string

Source of the feedback loop. Retrieved only when ShowExtraData=true.

MessageID

integer

Unique numeric ID for this message.

Open

boolean

Indicates whether the message was opened or not.

Queued

boolean

Indicates whether the message is still in queueing process or not.

Sent

boolean

Indicates whether the message was sent or not.

Spam

boolean

Indicates whether a spam complaint has been registered for this message or not.

StateID

integer

Unique numeric ID for the non-delivery state of the message. It gives a reference to why a message was not delivered successfully to the recipient. The property is only displayed when the message was not delivered successfully.

  • 1 = user unknown (recipient)
  • 2 = mailbox inactive (recipient)
  • 3 = quota exceeded (recipient)
  • 4 = invalid domain (domain)
  • 5 = no mail host (domain)
  • 6 = relay/access denied (domain)
  • 7 = sender blocked (spam)
  • 8 = content blocked (spam)
  • 9 = policy issue (spam)
  • 10 = system issue (system)
  • 11 = protocol issue (system)
  • 12 = connection issue (system)
  • 13 = greylisted (domain)
  • 14 = preblocked (Mailjet)
  • 15 = duplicate in campaign (Mailjet)
  • 16 = spam preblocked (Mailjet)
  • 17 = bad or empty template (content)
  • 18 = error in template language (content)
  • 19 = typofix (domain)
  • 20 = blacklisted (recipient)
  • 21 = spam reporter (recipient)

StatePermanent

boolean

Indicates whether the current non-delivery state is a permanent one or not.

Status

string

Displays the current message status.

Possible values:

  • queued
  • sent
  • opened
  • clicked
  • bounced
  • spam
  • unsub
  • blocked

ToEmail

string

Displays the email address of the recipient.

Unsub

boolean

Indicates whether the recipient unsubscribed from this email or not.

WorkflowID

integer

Unique numeric ID of the automation workflow that triggered the sending of this message.

Total

integer

get

/messagesentstatistics/{message_ID}

Retrieve an event summary for a specific message. It will provide information on each event type and whether it occurred for this message, as well as general sending information.

Note: This is a legacy endpoint, which is not available for users created after March 15th 2018. In order to receive event summaries for messages, please use the /message endpoint instead.

Full API path

https://api.mailjet.com/v3/REST/messagesentstatistics/{message_ID}

Path parameters

message_ID

integer, required

Unique numeric ID of the message you want to retrieve.

Responses

Note: You can find all the errors related to API in the error page

Count

integer

Data

array

ArrivalTs

string

Timestamp indicating when the message arrived in the recipient's mailbox.

Blocked

boolean

Indicates whether the message was blocked or not.

Bounce

boolean

Indicates whether the message has bounced or not.

BounceDate

string

Timestamp for the bounce event. Only available when ShowExtraData=true.

BounceReason

string

A short description indicating what the reason behind the bounce is. Only available when ShowExtraData=true.

CampaignID

integer

Unique numeric ID for the campaign this message is part of.

Click

boolean

Indicates whether a link in the email (except the unsubscription link) was clicked or not.

CntRecipients

integer

Shows the number of recipients for this campaign, when only the first message from each campaign is retrieved (AllMessages=false).

ComplaintDate

string

Timestamp for the time when the spam complaint was received for this message. Retrieved only when ShowExtraData=true.

ContactID

integer

Unique numeric ID for the contact, to which the message was sent.

Details

string

Indicates the reason for the non-delivery of a message.

FBLSource

string

Source of the feedback loop. Retrieved only when ShowExtraData=true.

MessageID

integer

Unique numeric ID for this message.

Open

boolean

Indicates whether the message was opened or not.

Queued

boolean

Indicates whether the message is still in queueing process or not.

Sent

boolean

Indicates whether the message was sent or not.

Spam

boolean

Indicates whether a spam complaint has been registered for this message or not.

StateID

integer

Unique numeric ID for the non-delivery state of the message. It gives a reference to why a message was not delivered successfully to the recipient. The property is only displayed when the message was not delivered successfully.

  • 1 = user unknown (recipient)
  • 2 = mailbox inactive (recipient)
  • 3 = quota exceeded (recipient)
  • 4 = invalid domain (domain)
  • 5 = no mail host (domain)
  • 6 = relay/access denied (domain)
  • 7 = sender blocked (spam)
  • 8 = content blocked (spam)
  • 9 = policy issue (spam)
  • 10 = system issue (system)
  • 11 = protocol issue (system)
  • 12 = connection issue (system)
  • 13 = greylisted (domain)
  • 14 = preblocked (Mailjet)
  • 15 = duplicate in campaign (Mailjet)
  • 16 = spam preblocked (Mailjet)
  • 17 = bad or empty template (content)
  • 18 = error in template language (content)
  • 19 = typofix (domain)
  • 20 = blacklisted (recipient)
  • 21 = spam reporter (recipient)

StatePermanent

boolean

Indicates whether the current non-delivery state is a permanent one or not.

Status

string

Displays the current message status.

Possible values:

  • queued
  • sent
  • opened
  • clicked
  • bounced
  • spam
  • unsub
  • blocked

ToEmail

string

Displays the email address of the recipient.

Unsub

boolean

Indicates whether the recipient unsubscribed from this email or not.

WorkflowID

integer

Unique numeric ID of the automation workflow that triggered the sending of this message.

Total

integer