client.Signatures
Every method in this namespace: its signature, its parameters, what it returns and an example.
Methods
The signatures each address keeps: list them, add one, rename or rewrite it, choose which one signs new mail and which one signs replies and forwards, copy one to other addresses, and delete it.
Signatures.List
List the signatures of the workspace or of one address, a page at a time
List(ctx context.Context, opts ...openemail.RequestOption) (*openemail.Page, error)Returns one page of signatures, sorted by address and then oldest first. ListAll collects every page and Iterate walks them lazily. An address keeps a list of named signatures, as its Signature tab in the app shows. At most one of them is the default for new mail (isDefault) and at most one the default for replies and forwards (isReplyDefault), and one signature can be both.
Give openemail.WithAddress to read the signatures of one address, or of a catch-all with *@example.com. Without it the list holds every address. An address that only ever had the single signature of earlier versions shows it here as one signature called Signature, default for both.
Emails.Send adds the default of the address it sends from, and takes signatureId to add any other signature of that address instead.
Parameters
openemail.WithAddressstringOne address, such as
[email protected], or*@example.comfor the catch-all of a domain. Left out, every address is listed.openemail.WithLimitintPage size, from 1 to 100. The server defaults to 25.
openemail.WithCursorstringThe
NextCursorof the previous page, passed back as it came. Leave it out for the first page.openemail.WithAPIKeystringOverrides the client API key for this call only.
Returns
A *openemail.Page with Items, HasMore and NextCursor. Each item has id, address, name, html, isDefault, isReplyDefault, createdAt and updatedAt.
Example
page, err := client.Signatures.List(ctx, openemail.WithAddress("[email protected]"))if err != nil { return err} for _, signature := range page.Items { fmt.Println(signature.String("name"), signature.Bool("isDefault"), signature.Bool("isReplyDefault"))} fmt.Println(page.HasMore, page.NextCursor)Notes
A key or an app limited to particular addresses or domains sees only the signatures of the addresses it holds, and those of a catch-all only when it holds the domain whole.
A value of
openemail.WithAddressthat is not an address, or that names a whole domain with@example.com, is a 422invalid_parameter.The cursor is opaque and holds where the last row sat in this order, so a signature added or deleted between pages never breaks the walk. A cursor this list did not hand out is a 400
invalid_cursor.
Also available in
Signatures.ListAll
Collect every signature into one slice
ListAll(ctx context.Context, opts ...openemail.RequestOption) ([]openemail.Object, error)Walks every page of List and returns with all signatures, sorted by address and then oldest first. One request per page. Give openemail.WithAddress to collect the signatures of one address or catch-all.
Parameters
openemail.WithAddressstringOne address, or
*@example.comfor a catch-all. Left out, every address is collected.openemail.WithLimitintPage size for each request, from 1 to 100. The server defaults to 25.
openemail.WithCursorstringStarts the walk after this cursor instead of the first page.
openemail.WithAPIKeystringOverrides the client API key for every page of this walk.
Returns
A []openemail.Object holding every signature.
Example
signatures, err := client.Signatures.ListAll(ctx, openemail.WithAddress("[email protected]"))if err != nil { return err} for _, signature := range signatures { if signature.String("name") != "Short" { continue } sent, err := client.Emails.Send(ctx, openemail.Body{ "from": "[email protected]", "to": "[email protected]", "subject": "Quick note", "text": "See you on Thursday.", "signatureId": signature.ID(), }) if err != nil { return err } fmt.Println(sent.ID(), sent.String("status"))}Notes
If any page fails the call fails and the signatures already fetched are discarded.
Also available in
Signatures.Iterate
Stream the signatures one at a time
Iterate(ctx context.Context, opts ...openemail.RequestOption) *openemail.IteratorReturns an iterator that yields signatures individually, sorted by address and then oldest first, and requests the next page only once the current one is drained. Nothing is fetched until you consume it, and breaking out of the loop stops the requests.
Parameters
openemail.WithAddressstringOne address, or
*@example.comfor a catch-all. Left out, every address is walked.openemail.WithLimitintPage size for each request, from 1 to 100. The server defaults to 25.
openemail.WithCursorstringStarts the walk after this cursor instead of the first page.
openemail.WithAPIKeystringOverrides the client API key for every page of this walk.
Returns
An *openemail.Iterator yielding one signature per step.
Example
for signature, err := range client.Signatures.Iterate(ctx).All() { if err != nil { return err } if signature.Bool("isDefault") { fmt.Println(signature.String("address"), "signs new mail with", signature.String("name")) }}Notes
The iterator is lazy, so an abandoned loop costs only the pages you consumed.
Also available in
Signatures.Get
Read one signature by id
Get(ctx context.Context, id string, opts ...openemail.RequestOption) (openemail.Object, error)Looks up a single signature and returns it in the same shape as a row of List: the address it belongs to, its name, its HTML and whether it is the default for new mail, for replies and forwards, for both or for neither.
Parameters
idstringRequiredSignature id, which starts with
sig_.openemail.WithAPIKeystringOverrides the client API key for this call only.
Returns
An openemail.Object with id, address, name, html, isDefault, isReplyDefault, createdAt and updatedAt.
Example
signature, err := client.Signatures.Get(ctx, "sig_8f2c1a9b7d3e4f60a1b2c3d4")if err != nil { return err} fmt.Println(signature.String("address"), signature.String("name"), signature.String("html"))Notes
A missing signature fails with an
*openemail.Errorthat matchesopenemail.ErrNotFoundand coderesource_not_found. So does one on an address a narrowed key does not hold.
Also available in
- API
GET /signatures/{id}- TypeScript
signatures.get()- Python
signatures.get()- Ruby
signatures.get- PHP
signatures->get- Java
signatures().get- C#
Signatures.GetAsync- CLI
openemail signatures get
Signatures.Create
Add a signature to an address
Create(ctx context.Context, body openemail.Body, opts ...openemail.RequestOption) (openemail.Object, error)Adds a signature to one address, or to a catch-all with *@example.com, and returns with it as it is stored. name is what the app calls it and is unique on its address, whatever the case, so a second Work on the same address is a 409 signature_name_taken. html is sanitised the way outgoing mail is and has to keep some text or an image, so the stored HTML can differ from what you sent.
The first signature of an address becomes its default for new mail and for replies and forwards, unless isDefault or isReplyDefault says false. A later signature becomes a default only when you ask, and then takes that place from the signature that held it. An address holds at most 50 signatures, and the call past that is a 422 signature_limit_reached.
The address has to be one of the workspace, or a catch-all on a verified domain here with its catch-all on.
Parameters
addressstringRequiredThe address the signature is for, such as
[email protected], or*@example.comfor the catch-all of a domain.namestringRequiredWhat the signature is called, trimmed, 1 to 80 characters. Unique on its address, whatever the case.
htmlstringRequiredThe signature as HTML, at most 150,000 characters before and after sanitising. It has to keep some text or an image.
isDefaultbooltruemakes it the signature of new mail from the address. Left out, only the first signature of an address becomes that.isReplyDefaultbooltruemakes it the signature of replies and forwards from the address. Left out, only the first signature of an address becomes that.openemail.WithAPIKeystringOverrides the client API key for this call only.
Returns
An openemail.Object with the new id, the trimmed name, the sanitised html, isDefault and isReplyDefault.
Example
signature, err := client.Signatures.Create(ctx, openemail.Body{ "address": "[email protected]", "name": "Short", "html": "<p>Ada<br>Acme Ltd</p>", "isReplyDefault": true,})if err != nil { return err} fmt.Println(signature.String("id"), signature.Bool("isDefault"), signature.Bool("isReplyDefault"))Notes
The SDK does not retry a create after a network failure. If you retry by hand after a lost response, a 409
signature_name_takenmeans the first attempt succeeded.A key or an app limited to particular addresses or domains can only add to an address it holds, and to a catch-all only when it holds the domain whole. Anything else is a 422
capability_unsupported.Copyputs the same signature on other addresses.
Also available in
Signatures.Update
Rename a signature, rewrite it or change what it is the default for
Update(ctx context.Context, id string, patch openemail.Body, opts ...openemail.RequestOption) (openemail.Object, error)Changes a signature and returns with it as it is stored. Send any of name, html, isDefault and isReplyDefault: a field left out stays as it is, and a patch with none of them is a 422.
isDefault: true makes it the signature of new mail from its address in place of the one that was. isDefault: false takes that away when this signature held it, so new mail from the address goes out with no signature until another one is chosen. isReplyDefault does the same for replies and forwards. The two are independent, so one signature can sign new mail and another, shorter one the replies.
A new name another signature of the address already has, compared without case, is a 409 signature_name_taken. The HTML is sanitised again and has to keep some text or an image. A message that is already scheduled picks up the new HTML when it goes out.
Parameters
idstringRequiredSignature id, which starts with
sig_.namestringNew name, trimmed, 1 to 80 characters. Left out, the name stays.
htmlstringNew HTML, at most 150,000 characters before and after sanitising. Left out, the HTML stays.
isDefaultbooltruemakes it the default for new mail,falsetakes that away when it held it. Left out, nothing changes.isReplyDefaultbooltruemakes it the default for replies and forwards,falsetakes that away when it held it. Left out, nothing changes.openemail.WithAPIKeystringOverrides the client API key for this call only.
Returns
An openemail.Object with the unchanged id and address and the new name, html, isDefault and isReplyDefault.
Example
saved, err := client.Signatures.Update(ctx, "sig_8f2c1a9b7d3e4f60a1b2c3d4", openemail.Body{"isDefault": true})if err != nil { return err} fmt.Println(saved.String("name"), saved.Bool("isDefault"))Notes
The SDK retries this call after a network failure, since the same patch sent twice leaves the same signature.
Settings.Updatewith an address still takessignature: it rewrites the HTML of the default for new mail, and adds a signature calledSignaturewhen the address has no default.
Also available in
Signatures.Delete
Delete a signature
Delete(ctx context.Context, id string, opts ...openemail.RequestOption) (openemail.Object, error)Deletes a signature for good. When it was a default, that default is left empty, so mail it would have signed goes out with no signature until another one is chosen with Update. A scheduled message that named it with signatureId carries the default of its address instead. There is no undo.
Parameters
idstringRequiredSignature id, which starts with
sig_.openemail.WithAPIKeystringOverrides the client API key for this call only.
Returns
An openemail.Object with object set to signature, id, address and deleted set to true.
Example
removed, err := client.Signatures.Delete(ctx, "sig_8f2c1a9b7d3e4f60a1b2c3d4")if err != nil { return err} fmt.Println(removed.String("address"), removed.Bool("deleted"))Notes
The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked.
Also available in
Signatures.Copy
Copy a signature to other addresses
Copy(ctx context.Context, id string, body openemail.Body, opts ...openemail.RequestOption) ([]openemail.Object, error)Puts a copy of a signature on up to 500 other addresses or catch-alls, as Copy to other addresses does in the app, and returns with the copies. An address that already has a signature with the same name, whatever the case, gets its HTML replaced, so copying again after an edit brings every copy up to date. Any other address gets a new signature with that name.
A copy becomes the default for new mail where isDefault is true and the default for replies and forwards where isReplyDefault is true. On an address that had no signature at all it becomes both unless you say false. Left out, the defaults of the other addresses stay as they are.
The address the signature is already on is skipped. Each copy is its own signature from then on, with its own id: editing the original later changes no copy until you copy again.
Parameters
idstringRequiredThe signature to copy.
addresses[]stringRequired1 to 500 addresses to copy it to. Each is one address or
*@example.comfor a catch-all.isDefaultbooltruemakes each copy the default for new mail on its address.isReplyDefaultbooltruemakes each copy the default for replies and forwards on its address.openemail.WithAPIKeystringOverrides the client API key for this call only.
Returns
A []openemail.Object, one copy for each address, in the order given.
Example
copies, err := client.Signatures.Copy(ctx, "sig_8f2c1a9b7d3e4f60a1b2c3d4", openemail.Body{ "addresses": []string{"[email protected]", "[email protected]"}, "isDefault": true,})if err != nil { return err} for _, signature := range copies { fmt.Println(signature.String("address"), signature.String("id"), signature.Bool("isDefault"))}Notes
The copies are written one address at a time. When an address is full, the call fails with 422
signature_limit_reachedand the addresses before it keep their copy, so the same call can be sent again once there is room.The SDK retries this call after a network failure, since copying twice leaves the same signatures.
A key or an app limited to particular addresses or domains can only copy to addresses it holds. One it does not hold fails the whole call with 422
capability_unsupportedbefore anything is written.