API v1
v1
View as Markdown

List emails sent

GET /api/v1/emails-sent

List the emails we sent on behalf of your account, most recently sent first.

This is the same record the emails screen in your settings shows, which is where to look when somebody says a sign-in link never arrived. Each email carries the three moments that can happen to it, when it left, when it arrived and when it came back, and one word that reads them for you.

The copy of each email is deliberately left out of this list. A page holds twenty five emails by default, and carrying the full text of each would turn a list somebody is scanning into a download. Ask for one email to read what it said.

The record belongs to the account rather than to you personally, so an email we sent to an address that has no account of its own is still listed here.

Nothing here can be written, changed or removed. The record is written as the mail leaves and updated only when the provider tells us what became of it.

This endpoint also answers QUERY, with the same parameters sent in the request body. How QUERY works.

Query parameters

Sent as JSON. Anything not listed here is ignored.

page integer Optional default: 1

Which page to answer with.

per_page integer Optional default: 25

How many emails one page holds, between 1 and 100. A number outside the range is brought back into it rather than refused.

Returns

A page of emails we sent, and how many there are in all. An account that has never had an email leave gets an empty list rather than an error.

data array

The emails on this page. An empty list rather than an error when there are none.

data[] object

One email.

data[].type string

Always email_sent. It names the kind of record, so a caller holding several kinds can tell them apart without looking at where they came from.

data[].id string

The id of this record, as a string even when it reads as a number. It is what every endpoint naming this record takes.

data[].attributes object

Everything the record holds.

data[].attributes.email_type string

Which of our emails this was, as a key such as new_login or magic_link_created, up to 255 characters. The keys come from a set the product keeps and adds to as it sends new kinds of mail, so match the ones you care about and let an unfamiliar one through rather than treating it as an error.

data[].attributes.subject string

The subject line as it was sent, of no fixed length, or null for a record written before we kept them.

data[].attributes.email_address string

The address it went to, up to 255 characters. It need not belong to anybody with an account: what matters is that it left on behalf of yours.

data[].attributes.delivery_status string

Where the email got to: one of complained, bounced, delivered or sent. It is the one word you want out of the four moments below, worked out the same way the account screen works it out, and read in that order, so a complaint outranks a bounce and either outranks a delivery when a provider reports them out of order.

data[].attributes.sent_at timestamp

When it left us, as a count of seconds since 1970, or null for a record written before we kept it. This is the moment the list is ordered by.

data[].attributes.delivered_at timestamp

When the provider told us it arrived, as a count of seconds, or null when nobody has told us. Null means we have not heard, not that it failed.

data[].attributes.bounced_at timestamp

When it came back, as a count of seconds, or null when it has not. An email with a moment here reached nobody, whether the receiving server refused it or our provider never managed to send it at all.

data[].attributes.complained_at timestamp

When the recipient marked it as spam, as a count of seconds, or null when they have not. It is a separate fact from a bounce: the address works, the person did not want the email.

data[].attributes.created_at timestamp

When the record was written, as a count of seconds. Usually the same second it was sent, and not the same field.

data[].links object

Where to find this record.

data[].links.self string

The absolute address this record is read from.

meta object

Where you are in the collection.

meta.page integer

The page this is, counting from 1.

meta.per_page integer

How many one page holds, which is the size that was asked for once it has been brought into the allowed range.

meta.total integer

How many emails there are in all, not how many are on this page.

Rate limit

Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in X-RateLimit-Remaining.

GET
curl https://my.monicahq.com/api/v1/emails-sent \
-H "Authorization: Bearer $MONICA_TOKEN"
const response = await fetch('https://my.monicahq.com/api/v1/emails-sent', {
headers: { Authorization: `Bearer ${token}` },
})
const data = await response.json()
$response = Http::withToken($token)->get('https://my.monicahq.com/api/v1/emails-sent');
Response 200
{
"data": [
{
"type": "email_sent",
"id": "42",
"attributes": {
"email_type": "new_login",
"subject": "A sign-in from a new place",
"email_address": "[email protected]",
"delivery_status": "delivered",
"sent_at": 1756339200,
"delivered_at": 1756339260,
"bounced_at": null,
"complained_at": null,
"created_at": 1756339200
},
"links": {
"self": "https://my.monicahq.com/api/v1/emails-sent/42"
}
},
{
"type": "email_sent",
"id": "41",
"attributes": {
"email_type": "magic_link_created",
"subject": "Your sign-in link",
"email_address": "[email protected]",
"delivery_status": "bounced",
"sent_at": 1756252800,
"delivered_at": null,
"bounced_at": 1756252860,
"complained_at": null,
"created_at": 1756252800
},
"links": {
"self": "https://my.monicahq.com/api/v1/emails-sent/41"
}
}
],
"meta": {
"page": 1,
"per_page": 25,
"total": 2
}
}

Keys act as you, with exactly the access you have. Make one per integration so you can revoke it alone.