/v1/me/mail/signaturesA composer needs a few things before it can draw itself: the sign-offs to offer, which of them is already filled in, and whether to offer the writing help. All of them come back here, so opening a composer is one call rather than three.
The list is already narrowed to the caller. A signature that belongs to one colleague is theirs alone and never appears for anybody else, and neither does one belonging to a mailbox this account cannot open. Feed the ids straight to send a message or save a draft.
Which one is filled in
meta.defaults answers that per mailbox, keyed by mailbox id, with the id of
a signature as the value. It is worked out
here rather than left to the client, because four levels decide it and the order
between them is not something an app should be reimplementing:
- What this person starts with on this mailbox.
- What this person starts with on any mailbox.
- What this mailbox gives anyone who has nothing of their own.
- The propfirm's house sign-off.
The first one that exists wins. That is what a shared mailbox needs: two
colleagues answering info@ each get their own name under the message without
either of them picking anything.
A mailbox that starts on nothing is present with null rather than left out, so
you can tell it apart from a mailbox you did not ask about.
Request
curl "https://api.proppertrading.com/v1/me/mail/signatures?mailbox=mbx_w6sy3skvgydh5e3b" \
-H "Authorization: Bearer ptat_9f2c1a44_3b8e7d2f5c9a1b4e6d8f0a2c4e6b8d1f"
| Parameter | Type | Description |
|---|---|---|
mailbox | string | Only what may be used from this mailbox, and only its default, by id from the mailbox list. An id the caller cannot read, a number included, is ignored rather than refused, and you get the unnarrowed list |
Response
{
"data": [
{
"id": "sig_dm8cfrz4cvdwh8we",
"object": "mail_signature",
"name": "Propper",
"html": "<p>Kind regards,<br>The Propper team</p>",
"mailbox_id": null,
"is_personal": false
},
{
"id": "sig_khuz893vv6fzuusz",
"object": "mail_signature",
"name": "Mick",
"html": "<p>Kind regards,<br>Mick</p>",
"mailbox_id": null,
"is_personal": true
}
],
"meta": {
"defaults": {
"mbx_w6sy3skvgydh5e3b": "sig_khuz893vv6fzuusz"
},
"writing_help": true,
"has_more": false,
"next_cursor": null,
"request_id": "req_01kz4bkr1aj1gv63d8fv3133ey"
}
}
| Field | Type | Description |
|---|---|---|
id | string | The signature, such as sig_khuz893vv6fzuusz. What signature_id takes when you send or save a draft |
mailbox_id | string | The id of the one mailbox that offers it, or null when every mailbox does |
is_personal | boolean | True when it belongs to the caller rather than to the whole team. Two people may each call theirs "Kind regards", and this is what tells them apart in a picker |
House sign-offs come first, then the caller's own, each group by name. Everything
comes back in one go: a propfirm has a handful of signatures, so there is no
cursor and has_more is always false.
An account with no mailboxes at all gets an empty list and an empty defaults,
not an error.
The writing help
meta.writing_help says whether to offer the writing help
in the composer: true when the environment has AI connected and switched on. It
does not look at the allowance. An option that disappears halfway through the
week looks like a bug, so it stays, and a call made after the allowance ran out
says so with assist_limit_reached.
Errors
| Status | Code | Meaning |
|---|---|---|
| 403 | insufficient_scope | This device does not hold mail:read |
| 403 | mailbox_not_permitted | This account may not open a mailbox |