Create contact
create_contactRecord a person in MailFathom's contact book with name, addresses, preferred address, and note. If an address is already held by another contact, the write is refused and that contact is returned.
Instructions
Records a person in MailFathom's own contact book: their name, every address they use, which one is preferred, and an optional note. Writes to local state only — nothing is sent to a mail server or to anybody else, and no mail is touched. Calling twice with the same person records them once and then answers addressHeldByAnotherContact, because one address belongs to one contact across the whole book; look that contact up with get_contact rather than writing a second record. Ask the person you are acting for before writing somebody down.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | What to record about this person, up to 4000 characters, or omit for none. Line breaks and tabs are kept. This is free text about a third party: write only what the person you are acting for asked to be recorded. | |
| addresses | Yes | Every mail address this person uses, at most 32 entries of at most 320 characters each. Two spellings of one address are stored once and the first spelling is the one kept, but both still count towards the 32. An address another contact already holds refuses the write. | |
| displayName | Yes | The name to record for this person, as it should be read back, up to 256 characters. Characters that render as nothing are refused. | |
| preferredAddress | Yes | The address to use when addressing this person without naming which of theirs to use. Must be one of addresses; state it even where the record names a single address, because nothing picks one for the owner. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | How the write ended. written means the book holds the record; notFound means no contact of that identifier is in the book; addressHeldByAnotherContact means one of the addresses already belongs to somebody else, named by addressHolderContactId; contactWasCollected means the record came from mail that arrived rather than from somebody writing it down, so promote_contact it before amending it; alreadyAsserted means a promotion had nothing left to do. | |
| contact | No | The record as the book now holds it, or null. Only a write whose record you supplied publishes one: create_contact, update_contact, add_contact_address, and remove_contact_address answer with the record when they succeed, while promote_contact answers with the outcome alone and is read back with get_contact. | |
| addressHolderContactId | No | The identifier of one contact that already holds an address this write claimed, or null when that is not what stopped it. Read that contact with get_contact to see who it is; a record may clash with more than one person, and this names one of them. |